path: root/upstream/odl-aaa-moon/aaa/aaa-authn-api/src/main/docs/sssd_configuration.rst

################################################
Federated Authentication Utilizing Apache & SSSD
################################################

:Author: John Dennis
:Email: jdennis@redhat.com

.. contents:: Table of Contents

************
Introduction
************

Applications should not need to handle the burden of authentication
and authorization. These are complex technologies further complicated
by the existence of a wide variety of authentication
mechanisms. Likewise there are numerous identity providers (IdP) which
one may wish to utilize, perhaps in a federated manner. The potential
to make critical mistakes are high while consuming significant
engineering resources. Ideally an application should "outsource" it's
authentication to an "expert" and avoid unnecessary development costs.

For web based applications (both conventional HTML and REST API) there
has been a trend to embed a simple HTTP server in the application or
application server which handles the HTTP requests eschewing the use
of a traditional web server such as Apache.

.. figure:: sssd_01.png
   :align: center

   _`Figure 1.`

But traditional web servers have a lot of advantages. They often come
with extensive support for technologies you might wish to utilize in
your application. It would require signification software engineering
to add support for those technologies in your application. The problem
is compounded by the fact many of these technologies demand domain
expertise which is unlikely to be available in the application
development team. Another problem is the libraries needed to utilize
the technology may not even be available in the programming language
the application is being developed in. Fundamentally an application
developer should focus on developing their application instead of
investing resources into implementing complex code for the ancillary
technologies the application may wish to utilize.

Therefore fronting your application with a web server such as Apache
makes a lot of sense. One should allow Apache to handle complex tasks
such as multiple authentication mechanisms talking to multiple
IdP's. Suppose you want your application to handle Single Sign-On
(SSO) via Kerberos or authentication based on X509 certificates
(i.e. PKI). Apache already has extensions to handle these which have
been field proven, it would be silly to try and support these in your
application. Apache also comes with other useful extensions such as
``mod_identity_lookup`` which can extract metadata about an
authenticated user from multiple sources such as LDAP,
Active Directory, NIS, etc.

By fronting your application with Apache and allowing Apache to handle
the complex task of authentication, identity lookups etc. you've
greatly increased the features of your application while at the same
time reducing application development time along with increasing
application security and robustness.

.. figure:: sssd_02.png
   :align: center

   _`Figure 2.`

When Apache fronts your application you will be passed the results of
authentication and identity lookups. Your application only needs a
simple mechanism to accept these values. There are a variety of ways
the values can be passed from Apache to your application which will be
discussed in later sections.

Authentication & Identity Properties
====================================

Authentication is proving that a user is who they claim to be, in
other words after authentication the user has a proven identity. In
security parlance the authenticated entity is call a
principal. Principals may be humans, machines or
services. Authorization is distinct from authentication. Authorization
declares what actions an authenticated principal may perform. For
example, does a principal have permission to read a certain file, run
a specific command, etc. Identity metadata is typically bound to the
principal to provide extra information. Examples include the users
full name, their organization, the groups they are members of, etc.

Apache can provide both authentication and identity metadata to an
application freeing the application of this task. Authorization
usually will remain the province of the application. A typical
design pattern is to assign roles to a principal based on identity
properties. As the application executes on behalf of a principal the
application will check if the principal has the necessary role needed
to perform the operation.

Apache ships with a wide variety of authentication modules. After an
Apache authentication module successfully authenticates a principal, it
sets internal variables identifying the principal and the
authentication method used to authenticate the principal. These are
exported as the CGI variables REMOTE_USER and AUTH_TYPE respectively
(see `CGI Export Issues`_ for further information).

Identity Properties
-------------------

Most Apache authentication modules do not have access to any of the
identity properties bound to the authenticated principal. Those
identity properties must be provided by some other mechanism. Typical
mechanisms include lookups in LDAP, Active Directory, NIS, POSIX
passwd/gecos and SQL. Managing these lookups can be difficult
especially in a networked environment where services may be
temporarily unavailable and/or in a enterprise deployment where
identity sources must be multiplexed across a variety of services
according to enterprise wide policy.

`SSSD`_ (System Security Services Daemon) is designed to alleviate many
of the problems surrounding authentication and identity property
lookup. SSSD can provide identity properties via D-Bus using it's
InfoPipe (IFP) feature. The `mod_identity_lookup`_ Apache module is
given the name of the authenticated principal and makes available
identity properties via Apache environment variables (see `Configure
SSSD IFP`_ for details).

Exporting & Consuming Identity Metadata
=======================================

The authenticated principal (REMOTE_USER), the mechanism used to
authenticate the principal (AUTH_TYPE) and identity properties
(supplied by SSSD IFP) are exported to the application which trusts
this metadata to be valid.

How is this identity metadata exported from Apache and then be
consumed by a Java EE Servlet?

The architectural design inside Apache tries to capitalize on the
existing CGI standard (`CGI RFC`_) as much as possible. CGI defines
these relevant environment variables:

  * REMOTE_USER
  * AUTH_TYPE
  * REMOTE_ADDR
  * REMOTE_HOST


Transporting Identity Metadata from Apache to a Java EE Servlet
===============================================================

In following figure we can see that the user connects to Apache
instead of the servlet container. Apache authenticates the user, looks
up the principal's identity information and then proxies the request
to the servlet container. The additional identity metadata must be
included in the proxy request in order for the servlet to extract it.

.. figure:: sssd_03.png
   :align: center

   _`Figure 3.`

The Java EE Servlet API is designed with the HTTP protocol in mind
however the servlet never directly accesses the HTTP protocol stream.
Instead it uses the servlet API to get access to HTTP request
data. The responsibility for HTTP communication rests with the
container's ``Connector`` objects. When the servlet API needs
information it works in conjunction with the ``Connector`` to supply
it. For example the ``HttpServletRequest.getRemoteHost()`` method
interrogates information the ``Connector`` placed on the internal
request object. Analogously ``HttpServletRequest.getRemoteUser()``
interrogates information placed on the internal request object by an
authentication filter.

But what happens when a HTTP request is proxied to a servlet container
by Apache and ``getRemoteHost()`` or ``getRemoteUser()`` is called? Most
``Connector`` objects do not understand the proxy scenario, to them
a request from a proxy looks just like a request sent directly to the
servlet container. Therefore ``getRemoteHost()`` or ``getRemoteUser()``
ends up returning information relative to the proxy instead of the
user who connected to the proxy because it's the proxy who connected
to the servlet container and not the end user. There are 2 fundamental
approaches which allow the servlet API to return data supplied by the
proxy:

  1. Proxy uses special protocol (e.g. AJP) to embed metadata.
  2. Metadata is embedded in an HTTP extension by the proxy (i.e. headers)

Proxy With AJP Protocol
-----------------------

The AJP_ protocol was designed as a protocol to exchange HTTP requests
and responses between Apache and a Java EE Servlet Container. One of
its design goals was to improve performance by translating common text
values appearing in HTTP requests to a more compact binary form. At
the same time AJP provided a mechanism to supply metadata about the
request to the servlet container. That metadata is encoded in an AJP
attribute (a name/value pair). The Apache AJP Proxy module looks up
information in the internal Apache request object (e.g. remote user,
remote address, etc.) and encodes that metadata in AJP attributes. On
the servlet container side a AJP ``Connector`` object is aware of these
metadata attributes, extracts them from the protocol and supplies
their values to the upper layers of the servlet API. Thus a call to
``HttpServletRequest.getRemoteUser()`` made by a servlet will receive
the value set by Apache prior to the proxy. This is the desired and
expected behavior. A servlet should be ignorant of the consequences of
proxies; the servlet API should behave the same regardless of the
presence of a proxy.

The AJP protocol also has a general purpose attribute mechanism whereby
any arbitrary name/value pair can be passed. This proxy metadata can
be retrieved by a servlet by calling ``ServletRequest.getAttribute()``
[1]_ When Apache mod_proxy_ajp is being used the authentication
metadata for the remote user and auth type are are automatically
inserted into the AJP protocol and the AJP ``Connector`` object on
the servlet receiving end supplies those values to
``HttpServletRequest.getRemoteHost()`` and
``HttpServletRequest.getRemoteUser()`` respectively. But the identity
metadata supplied by ``mod_identity_lookup`` needs to be explicitly
encoded into an AJP attribute (see `Configure SSSD IFP`_ for details)
that can later be retrieved by ``ServletRequest.getAttribute()``.

Proxy With HTTP Protocol
------------------------

Although the AJP protocol offers a number of nice advantages sometimes
it's not an option. Not all servlet containers support AJP or there
may be some other deployment constraint that precludes its use. In this
case option 2 from above needs to be used. Option 2 requires only the
defined HTTP protocol be used without any "out of band" metadata. The
conventional way to attach extension metadata to a HTTP request is to
add extension HTTP headers.

One problem with using extension HTTP headers to pass metadata to a
servlet is the expectation the servlet API will have the same
behavior. In other words the value returned by
``HttpServletRequest.getRemoteUser()`` should not depend on whether the
proxy request was exchanged with the AJP protocol or the HTTP
protocol. The solution to this is to wrap the ``HttpServletRequest``
object in a servlet filter. The wrapper overrides certain request
methods (e.g. ``getRemoteUser()``). The override method looks to see if
the metadata is in the extension HTTP headers, if so it returns the
value found in the extension HTTP header otherwise it defers to the
existing servlet implementation. The ``ServletRequest.getAttribute()`` is
overridden in an analogous manner in the wrapper filter. Any call to
``ServletRequest.getAttribute()`` is first checked to see if the value
exists in the extension HTTP header first.

Metadata supplied by Apache that is **not** part of the normal Java
EE Servlet API **always** appears to the servlet via the
``ServletRequest.getAttribute()`` method regardless of the proxy
transport mechanism. The consequence of this is a servlet
continues to utilize the existing Java EE Servlet API without concern
for intermediary proxies, *and* any other metadata supplied by a proxy
is *always* retrieved via ``ServletRequest.getAttribute()`` (see the
caveat about ``ServletRequest.getAttributeNames()`` [1]_).

*******************
Configuration Guide
*******************

Although Apache authentication and SSSD identity lookup can operate
with a variety of authentication mechanisms, IdP's and identity
metadata providers we will demonstrate a configuration example which
utilizes the FreeIPA_ IdP. FreeIPA excels at Kerberos SSO authentication,
Active Directory integration, LDAP based identity metadata storage and
lookup, DNS services, host based RBAC, SSH key management, certificate
management, friendly web based console, command line tools and many
other advanced IdP features.

The following configuration steps will need to be performed:

1. Install FreeIPA_ by following the installation guides in the FreeIPA_
   documentation area. When you install FreeIPA_ you will need to select a
   realm (a.k.a domain) in which your users and hosts will exist. In
   our example we will use the ``EXAMPLE.COM`` realm.

2. Install and configure the Apache HTTP web server. The
   recommendation is to install and run the Apache HTTP web server on
   the same system the Java EE Container running AAA is installed on.

3. Configure the proxy connector in the Java EE Container and set the
   ``secureProxyPorts``.

We will also illustrate the operation of the system by adding an
example user named ``testuser`` who will be a member of the
``odl_users`` and ``odl_admin`` groups.

Add Example User and Groups to FreeIPA
======================================

After installing FreeIPA you will need to populate FreeIPA with your users,
groups and other data. Refer to the documentation in FreeIPA_ for the
variety of ways this task can be performed; it runs the gamut from web
based console to command line utilities. For simplicity we will use
the command line utilities.

Identify yourself to FreeIPA as an administrator; this will give you the
necessary privileges needed to create and modify data in FreeIPA. You do
this by obtaining a Kerberos ticket for the ``admin`` user (or any
other user in FreeIPA with administrator privileges.

::

  % kinit admin@EXAMPLE.COM

Create the example ``odl_users`` and `odl_admin`` groups.

::

  % ipa group-add odl_users --desc 'OpenDaylight Users'
  % ipa group-add odl_admin --desc 'OpenDaylight Administrators'

Create the example user ``testuser`` with the first name "Test" and a
last name of "User" and an email address of "test.user@example.com"

::

  % ipa user-add testuser --first Test --last User --email test.user@example.com

Now add ``testuser`` to the ``odl_users`` and ``odl_admin`` groups.

::

  % ipa group-add-member odl_users --user testuser
  % ipa group-add-member odl_admin --user testuser

Configure Apache
================

A number of Apache configuration directives will need to be specified
to implement the Apache to application binding. Although these
configuration directives can be located in any number of different
Apache configuration files the most sensible approach is to co-locate
them in a single application configuration file. This greatly
simplifies the deployment of your application and isolates your
application configuration from other applications and services sharing
the Apache installation. In the examples that follow our application
will be named ``my_app`` and the Apache application configuration file
will be named ``my_app.conf`` which should be located in Apache's
``conf.d/`` directory. The web resource we are protecting and
supplying identity metadata for will be named ``my_resource``.


Configure Apache for Kerberos
-----------------------------

When FreeIPA is deployed Kerberos is the preferred authentication mechanism
for Single Sign-On (SSO). FreeIPA also provides identity metadata via
Apache ``mod_identity_lookup``. To protect your ``my_resource`` resource
with Kerberos authentication identify your resource as requiring
Kerberos authentication in your ``my_app.conf`` Apache
configuration. For example:

::

  <Location my_resource>
    AuthType Kerberos
    AuthName "Kerberos Login"
    KrbMethodNegotiate On
    KrbMethodK5Passwd Off
    KrbAuthRealms EXAMPLE.COM
    Krb5KeyTab /etc/http.keytab
    require valid-user
  </Location>

You will need to replace EXAMPLE.COM in the KrbAuthRealms declaration
with the Kerberos realm for your deployment.


Configure SSSD IFP
------------------

To use the Apache ``mod_identity_lookup`` module to supply identity
metadata you need to do the following in ``my_app.conf``:

1. Enable the module

   ::

     LoadModule lookup_identity_module modules/mod_lookup_identity.so

2. Apply the identity metadata lookup to specific URL's
   (e.g. ``my_resource``) via an Apache location directive. In this
   example we look up the "mail" attribute and assign it to the
   REMOTE_USER_EMAIL environment variable.

   ::

     <LocationMatch "my_resource">
       LookupUserAttr mail REMOTE_USER_EMAIL
     </LocationMatch>

3. Export the environment variable via the desired proxy protocol, see
   `Exporting Environment Variables to the Proxy`_

Exporting Environment Variables to the Proxy
--------------------------------------------

First you need to decide which proxy protocol you're going to use, AJP
or HTTP and then determine the target address and port to proxy to. The
recommended configuration is to run both the Apache server and the
servlet container on the same host and to proxy requests over the
local loopback interface (see `Declaring the Connector Ports for
Authentication Proxies`_). In our examples we'll use port 8383. Thus
in ``my_app.conf`` add a proxy declaration.

For HTTP Proxy

::

   ProxyPass / http://localhost:8383/
   ProxyPassReverse / http://localhost:8383/

For AJP Proxy

::

   ProxyPass / ajp://localhost:8383/
   ProxyPassReverse / ajp://localhost:8383/

AJP Exports
^^^^^^^^^^^

AJP automatically forwards REMOTE_USER and AUTH_TYPE making them
available to the ``HttpServletRequest`` API, thus you do not need to
explicitly forward these in the proxy configuration. However all other
``mod_identity_lookup`` metadata must be explicitly forwarded as an AJP
attribute. These AJP attributes become visible in the
``ServletRequest.getAttribute()`` method [1]_.

The Apache ``mod_proxy_ajp`` module automatically sends any Apache
environment variable prefixed with "AJP\_" as an AJP attribute which
can be retrieved with ``ServletRequest.getAttribute()``. Therefore the
``mod_identity_lookup`` directives which specify the Apache environment
variable to set with the result of a lookup must be prefixed with
"AJP\_". Using the above example of looking up the principal's email
address we modify the environment variable to include the "AJP\_"
prefix. Thusly:

   ::

     <LocationMatch "my_resource">
       LookupUserAttr mail AJP_REMOTE_USER_EMAIL
     </LocationMatch>

The sequence of events is as follows:

  1. When the URL matches "my_resource".

  2. ``mod_identity_lookup`` retrieves the mail attribute for the
     principal.

  3. ``mod_identity_lookup`` assigns the value of the mail attribute
     lookup to the AJP_REMOTE_USER_EMAIL Apache environment variable.

  4. ``mod_proxy_ajp`` encodes AJP_REMOTE_USER_EMAIL environment
     variable into an AJP attribute in the AJP protocol because the
     environment variable is prefixed with "AJP\_". The name of the
     attribute is stripped of it's "AJP\_" prefix thus the
     AJP_REMOTE_USER_EMAIL environment variable is transferred as the
     AJP attribute REMOTE_USER_EMAIL.

  5. The request is forwarded (i.e. proxied) to servlet container
     using the AJP protocol.

  6. The servlet container's AJP ``Connector`` object is assigned each AJP
     attribute to the set of attributes on the ``ServletRequest``
     attribute list. Thus a call to
     ``ServletRequest.getAttribute("REMOTE_USER_EMAIL")`` yields the
     value set by ``mod_identity_lookup``.


HTTP Exports
^^^^^^^^^^^^

When HTTP proxy is used there are no automatic or implicit metadata
transfers; every metadata attribute must be explicitly handled on both
ends of the proxy connection. All identity metadata attributes are
transferred as extension HTTP headers, by convention those headers are
prefixed with "X-SSSD-".

Using the original example of looking up the principal's email
address we must now perform two independent actions:

  1. Lookup the value via ``mod_identity_lookup`` and assign to an
     Apache environment variable.

  2. Export the environment variable in the request header with the
     "X-SSSD-" prefix.

   ::

     <LocationMatch "my_resource">
       LookupUserAttr mail REMOTE_USER_EMAIL
       RequestHeader set X-SSSD-REMOTE_USER_EMAIL %{REMOTE_USER_EMAIL}e
     </LocationMatch>

The sequence of events is as follows:

  1. When the URL matches "my_resource".

  2. ``mod_identity_lookup`` retrieves the mail attribute for the
     principal.

  3. ``mod_identity_lookup`` assigns the value of the mail attribute
     lookup to the REMOTE_USER_EMAIL Apache environment variable.

  4. Apache's RequestHeader directive executes just prior to the
     request being forwarded (i.e. in the Apache fixup stage). It adds
     the header X-SSSD-REMOTE_USER_EMAIL and assigns the value for
     REMOTE_USER_EMAIL found in the set of environment variables. It
     does this because the syntax %{XXX} is a variable reference for
     the name XXX and the 'e' appended after the closing brace
     indicates the lookup is to be performed in the set of environment
     variables.

  5. The request is forwarded (i.e. proxied) to the servlet container
     using the HTTP protocol.

  6. When ``ServletRequest.getAttribute()`` is called the ``SssdFilter``
     wrapper intercepts the ``getAttribute()`` method. It looks for an
     HTTP header of the same name with "X-SSSD-" prefixed to it. In
     this case ``getAttribute("REMOTE_USER_EMAIL")`` causes the lookup of
     "X-SSSD-REMOTE_USER_EMAIL" in the HTTP headers, if found that
     value is returned.

AJP Proxy Example Configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If you are using AJP proxy to the Java EE Container on port 8383 your
``my_app.conf`` Apache configuration file will probably look like
this:

::

  <LocationMatch "my_resource">

    ProxyPass / ajp://localhost:8383/
    ProxyPassReverse / ajp://localhost:8383/

    LookupUserAttr mail AJP_REMOTE_USER_EMAIL " "
    LookupUserAttr givenname AJP_REMOTE_USER_FIRSTNAME
    LookupUserAttr sn AJP_REMOTE_USER_LASTNAME
    LookupUserGroups AJP_REMOTE_USER_GROUPS ":"

  </LocationMatch>

Note the specification of the colon separator for the
``LookupUserGroups`` operation. [3]_

HTTP Proxy Example Configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If you are using a conventional HTTP proxy to the Java EE Container on
port 8383 your ``my_app.conf`` Apache configuration file will probably
look like this:

::

  <LocationMatch "my_resource">

    ProxyPass / http://localhost:8383/
    ProxyPassReverse / http://localhost:8383/

    RequestHeader set X-SSSD-REMOTE_USER expr=%{REMOTE_USER}
    RequestHeader set X-SSSD-AUTH_TYPE expr=%{AUTH_TYPE}
    RequestHeader set X-SSSD-REMOTE_HOST expr=%{REMOTE_HOST}
    RequestHeader set X-SSSD-REMOTE_ADDR expr=%{REMOTE_ADDR}

    LookupUserAttr mail REMOTE_USER_EMAIL
    RequestHeader set X-SSSD-REMOTE_USER_EMAIL %{REMOTE_USER_EMAIL}e

    LookupUserAttr givenname REMOTE_USER_FIRSTNAME
    RequestHeader set X-SSSD-REMOTE_USER_FIRSTNAME %{REMOTE_USER_FIRSTNAME}e

    LookupUserAttr sn REMOTE_USER_LASTNAME
    RequestHeader set X-SSSD-REMOTE_USER_LASTNAME %{REMOTE_USER_LASTNAME}e

    LookupUserGroups REMOTE_USER_GROUPS ":"
    RequestHeader set X-SSSD-REMOTE_USER_GROUPS %{REMOTE_USER_GROUPS}e

  </LocationMatch>

Note the specification of the colon separator for the
``LookupUserGroups`` operation. [3]_


Configure Java EE Container Proxy Connector
===========================================

The Java EE Container must be configured to listen for connections
from the Apache web server. A Java EE Container specifies connections
via a ``Connector`` object. A ``Connector`` **must** be dedicated
**exclusively** for handling authenticated requests from the Apache
web server. The reason for this is explained in `The Proxy
Problem`_. In addition ``ClaimAuthFilter`` needs to validate that any
request it processes originated from the trusted Apache instance. This
is accomplished by dedicating one or more ports exclusively for use by
the trusted Apache server and enumerating them in the
``secureProxyPorts`` configuration as explained in `Locking Down the
Apache to Java EE Container Channel`_ and `Declaring the Connector
Ports for Authentication Proxies`_.

Configure Tomcat Proxy Connector
--------------------------------

The Tomcat Java EE Container defines Connectors in its ``server.xml``
configuration file.

::

    <Connector
        address="127.0.0.1"
        port="8383"
        protocol="HTTP/1.1"
        tomcatAuthentication="false"
        connectionTimeout="20000"
        redirectPort="8443"
    />


:address:
  This should be the loopback address as explained `Locking Down the
  Apache to Java EE Container Channel`_.

:port:
  In our examples we've been using port 8383 as the proxy port. The
  exact port is not important but it must be consistent with the
  Apache proxy port, the ``Connector`` declaration, and the port value
  in ``secureProxyPorts``.

:protocol:
  As explained in `Transporting Identity Metadata from Apache to a
  Java EE Servlet`_ you will need to decide if you are using HTTP or
  AJP as the proxy protocol. In the example above the protocol is set
  for HTTP, if you use AJP instead the protocol should instead be
  "AJP/1.3".

:tomcatAuthentication:
  This boolean flag tells Tomcat whether Tomcat should perform
  authentication on the incoming requests or not. Since authentication
  is performed by Apache we do not want Tomcat to perform
  authentication therefore this flag must be set to false.

The AAA system needs to know which port(s) the trusted Apache proxy
will be sending requests on so it can trust the request authentication
metadata. See `Declaring the Connector Ports for Authentication
Proxies`_ for more information). Set ``secureProxyPorts`` in the
FederationConfiguration.

::

  secureProxyPorts=8383


Configure Jetty Proxy Connector
-------------------------------

The Jetty Java EE Container defines Connectors in its ``jetty.xml``
configuration file.

::

    <!-- Trusted Authentication Federation proxy connection -->
    <Call name="addConnector">
        <Arg>
            <New class="org.eclipse.jetty.server.nio.SelectChannelConnector">
                <Set name="host">127.0.0.1</Set>
                <Set name="port">8383</Set>
                <Set name="maxIdleTime">300000</Set>
                <Set name="Acceptors">2</Set>
                <Set name="statsOn">false</Set>
                <Set name="confidentialPort">8445</Set>
                <Set name="name">federationConn</Set>
                <Set name="lowResourcesConnections">20000</Set>
                <Set name="lowResourcesMaxIdleTime">5000</Set>
            </New>
        </Arg>
    </Call>

:host:
  This should be the loopback address as explained `Locking Down the
  Apache to Java EE Container Channel`_.

:port:
  In our examples we've been using port 8383 as the proxy port. The
  exact port is not important but it must be consistent with the
  Apache proxy port, the ``Connector`` declaration, and the port value
  in ``secureProxyPorts``.


Note, values in Jetty XML can also be parameterized so that they may
be passed from property files or set on the command line. Thus
typically the port is set within Jetty XML, but uses the Property
element to be customizable. Thus the above ``host`` and ``port``
properties could be specificed this way:

::

    <Set name="host">
        <Property name="jetty.host" default="127.0.0.1"/>
    </Set>
    <Set name="port">
        <Property name="jetty.port" default="8383"/>
    </Set>


The AAA system needs to know which port(s) the trusted Apache proxy
will be sending requests on so it can trust the request authentication
metadata. See `Declaring the Connector Ports for Authentication
Proxies`_ for more information). Set ``secureProxyPorts`` in the
FederationConfiguration.

************************************************
How Apache Identity Metadata is Processed in AAA
************************************************

`Figure 2.`_ and `Figure 3.`_ illustrates the fact the first stage in
processing a request from a user begins with Apache where the user is
authenticated and SSSD supplies additional metadata about the
user. The original request along with the metadata are subsequently
forwarded by Apache to the Java EE Container. `Figure 4.`_ illustrates
the processing inside the Java EE Container once it receives the
request on one of its secure connectors.


.. figure:: sssd_04.png
   :align: center

   _`Figure 4.`

:Step 1:
  One or more Connectors have been configured to listen for requests
  being forwarded from a trusted Apache instance. The Connector is
  configured to communicate using either the HTTP or AJP protocols.
  See `Exporting Environment Variables to the Proxy`_ for more
  information on selecting a proxy transport protocol.

:Step 2:
  The identity metadata bound to the request needs to be extracted
  differently depending upon whether HTTP or AJP is the transport
  protocol. To allow later stages in the pipeline to be ignorant of
  the transport protocol semantics the ``SssdFilter`` servlet filter
  is introduced. The ``SssdFilter`` wraps the ``HttpServletRequest``
  class and intercepts calls which might return the identity
  metadata. The wrapper in the filter looks in protocol specific
  locations for the metadata. In this manner users of the
  ``HttpServletRequest`` are isolated from protocol differences.


:Step 3:

  The ``ClaimAuthFilter`` is responsible for determining if identity
  metadata is bound to the request. If so all identity metadata is
  packaged into an assertion which is then handed off to
  ``SssdClaimAuth`` which will transform the identity metadata in the
  assertion into a AAA Claim which is the authorizing token for the user.

:Step 4:
  The ``SssdClaimAuth`` object is responsible for transforming the
  external federated identity metadata provided by Apache and SSSD into
  a AAA claim. The AAA claim is an authorization token which includes
  information about the user plus a set of roles. These roles provide the
  authorization to perform AAA tasks. Although how roles are assigned is
  flexible the expectation is domain and/or group membership will be the
  primary criteria for role assignment. Because deciding how to handle
  external federated identity metadata is site and deployment specific
  we need a loadable policy mechanism. This is accomplished by a set of
  transformation rules which transforms the incoming IdP identity
  metadata into a AAA claim. For greater clarity this important step is
  broken down into smaller units in the shaded box in `Figure 4.`_.

:Step 4.1:
  `The Mapping Rule Processor`_ is designed to accept a JSON object
  (set of key/value pairs) as input and emit a different JSON object
  as output effectively operating as a transformation engine on
  key/value pairs.

:Step 4.2:
  The input assertion is rewritten as a JSON object in the format
  required by the Mapping Rule Processor. The JSON assertion is then
  passed into the Mapping Rule Processor.

:Step 4.3:
  `The Mapping Rule Processor`_ identified as ``IdPMapper`` evaluates
  the input JSON assertion in the context of the mapping rules defined
  for the site deployment. If ``IdPMapper`` is able to successfully
  transform the input it will return a JSON object which we called the
  *mapped* result. If the input JSON assertion is not compatible with
  the site specific rules loaded into the ``IdPMapper`` then NULL is
  returned by the ``IdPMapper``.

:Step 4.4:
  If a mapped JSON object is returned by the ``IdPMapper`` the mapping
  was successful. The values in the mapped result are re-written into
  an AAA Claim token.

How Apache Identity Metadata is Mapped to AAA Values
====================================================

A federated IdP supplies metadata in a form unique to the IdP. This is
called an assertion. That assertion must be transformed into a format
and data understood by AAA. More importantly that assertion needs to
yield *authorization roles specific to AAA*. In `Figure 4.`_ Step 4.3
the ``IdPMapper`` provides the transformation from an external IdP
assertion to an AAA specific claim. It does this via a Mapping Rule
Processor which reads a site specific set of transformation
rules. These mapping rules define how to transform an external IdP
assertion into a AAA claim. The mapping rules also are responsible for
validating the external IdP claim to make sure it is consistent with
the site specific requirements. The operation of the Mapping Rule
Processor and the syntax of the mapping rules are defined in `The
Mapping Rule Processor`_.

Below is an example mapping rule which might be loaded into the
Mapping Rule Processor. It is assumed there are two AAA roles which
may be assigned [4]_:

``user``
  A role granting standard permissions for normal ODL users.

``admin``
  A special role granting full administrative permissions.

In this example assigning the ``user`` and ``admin`` roles
will be based on group membership in the following groups:

``odl_users``
  Members of this group are normal ODL users with restricted permissions.

``odl_admin``
  Members of this group are ODL administrators with permission to
  perform all operations.

Granting of the ``user`` and/or ``admin`` roles based on
membership in the ``odl_users`` and ``odl_admin`` is illustrated in
the follow mapping rule example which also extracts the user principal
and domain information in the preferred format for the site
(e.g. usernames are lowercase without domain suffixes and the domain
is uppercase and supplied separately).

_`Mapping Rule Example 1.`

::

  1   [
  2     {"mapping": {"ClientId": "$client_id",
  3            "UserId": "$user_id",
  4            "User": "$username",
  5            "Domain": "$domain",
  6            "roles": "$roles",
  7           },
  8      "statement_blocks": [
  9        [
  10         ["set", "$groups", []],
  11         ["set", "$roles", []]
  12       ],
  13       [
  14         ["in", "REMOTE_USER", "$assertion"],
  15         ["exit", "rule_fails", "if_not_success"],
  16         ["regexp", "$assertion[REMOTE_USER]", "(?<username>\\w+)@(?<domain>.+)"],
  17         ["exit", "rule_fails", "if_not_success"],
  18         ["lower", "$username", "$regexp_map[username]"],
  19         ["upper", "$domain", "$regexp_map[domain]"],
  20       ],
  21       [
  22         ["in", "REMOTE_USER_GROUPS", "$assertion"],
  23         ["exit", "rule_fails", "if_not_success"],
  24         ["split", "$groups", "$assertion[REMOTE_USER_GROUPS]", ":"],
  25       ],
  26       [
  27         ["in", "odl_users", "$groups"],
  28         ["continue", "if_not_success"],
  29         ["append", "$roles", "user"],
  30       ],
  31       [
  32         ["in", "odl_admin", "$groups"],
  33         ["continue", "if_not_success"],
  34         ["append", "$roles", "admin"]
  35       ],
  36       [
  37         ["unique", "$roles", "$roles"],
  38         ["length", "$n_roles", "$roles"],
  39         ["compare", "$n_roles", ">", 0],
  40         ["exit", "rule_fails", "if_not_success"],
  41       ],
  42     ]
  43    }
  44  ]

:Line 1:
  Starts a list of rules. In this example only 1 rule is defined. Each
  rule is a JSON object containing a ``mapping`` and a required list
  of ``statement_blocks``. The ``mapping`` may either be specified
  inside a rule as it is here or may be referenced by name in a table
  of mappings (this is easier to manage if you have a large number of
  rules and small number of mappings).

:Lines 2-7:
  Defines the JSON mapped result. Each key maps to AAA claim.  The
  value is a rule variable whose value will be substituted if the rule
  succeeds.  Thus for example the AAA claim value ``User`` will be
  assigned the value from the ``$username`` rule variable.
:Line 8:
  Begins the list of statement blocks. A statement must be contained
  inside a block.
:Lines 9-12:
  The first block usually initializes variables that will be
  referenced later. Here we initialize ``$groups`` and ``$roles`` to
  empty arrays. These arrays may be appended to in later blocks and
  may be referenced in the final ``mapping`` output.
:Lines 13-20:
  This block sets the user and domain information based on
  ``REMOTE_USER`` and exits the rule if ``REMOTE_USER`` is not defined.
:Lines 14-15:
  This test is critical, it assures ``REMOTE_USER`` is defined in the
  assertion, if not the rule is skipped because we depend on
  ``REMOTE_USER``.
:Lines 16-17:
  Performs a regular expression match against ``REMOTE_USER`` to split
  the username from the domain. The regular expression uses named
  groups, in this instance ``username`` and ``domain``. If the regular
  expression does not match the rule is skipped.
:Lines 18-19:
  These lines reference the previous result of the regular expression
  match which are stored in the special variable ``$regexp_map``. The
  username is converted to lower case and stored in ``$username`` and
  the domain is converted to upper case and stored in ``$domain``. The
  choice of case is purely by convention and site requirements.
:Lines 21-35:
  These 3 blocks assign roles based on group membership.
:Lines 21-25:
  Assures ``REMOTE_USER_GROUPS`` is defined in the assertion; if not, the
  rule is skipped. ``REMOTE_USER_GROUPS`` is colon separated list of group
  names. In order to operate on the individual group names appearing
  in ``REMOTE_USER_GROUPS`` line 24 splits the string on the colon
  separator and stores the result in the ``$groups`` array.
:Lines 27-30:
  This block assigns the ``user`` role if the user is a member of the
  ``odl_users`` group.
:Lines 31-35:
  This block assigns the ``admin`` role if the user is a
  member of the ``odl_admin`` group.
:Lines 36-41:
  This block performs final clean up actions for the rule. First it
  assures there are no duplicates in the ``$roles`` array by calling
  the ``unique`` function. Then it gets a count of how many items are
  in the ``$roles`` array and tests to see if it's empty. If there are
  no roles assigned the rule is skipped.
:Line 43:
  This is the end of the rule. If we reach the end of the rule it
  succeeds. When a rule succeeds the mapping associated with the rule
  is looked up. Any rule variable appearing in the mapping is
  substituted with its value.

Using the rules in `Mapping Rule Example 1.`_ and following example assertion
in JSON format:

_`Assertion Example 1.`

::

  {
    "REMOTE_USER": "TestUser@example.com",
    "REMOTE_AUTH_TYPE": "Negotiate",
    "REMOTE_USER_GROUPS": "odl_users:odl_admin",
    "REMOTE_USER_EMAIL": "test.user@example.com",
    "REMOTE_USER_FIRSTNAME": "Test",
    "REMOTE_USER_LASTNAME": "User"
  }

Then the mapper will return the following mapped JSON document. This
is the ``mapping`` defined on line 2 of `Mapping Rule Example 1.`_ with the
variables substituted after the rule successfully executed. Note any
valid JSON data type can be returned, in this example the ``null``
value is returned for ``ClientId`` and ``UserId``, normal strings for
``User`` and ``Domain`` and an array of strings for the ``roles`` value.

_`Mapped Result Example 1.`

::

  {
    "ClientId": null,
    "UserId": null,
    "User": "testuser",
    "Domain": "EXAMPLE.COM",
    "roles": ["user", "admin"]
  }


**************************
The Mapping Rule Processor
**************************

The Mapping Rule Processor is designed to be as flexible and generic
as possible. It accepts a JSON object as input and returns a JSON
object as output. JSON was chosen because virtually all data can be
represented in JSON, JSON has extensive support and JSON is human
readable. The rules loaded into the Mapping Rule Processor are also
expressed in JSON. One advantage of this is it makes it easy for a
site administrator to define hardcoded values which are always
returned and/or static tables of white and black listed users or users
who are always mapped into certain roles.

.. include:: mapping.rst

***********************
Security Considerations
***********************

Attack Vectors
==============

A Java EE Container fronted by Apache has by definition 2 major
components:

* Apache
* Java EE Container

Each of these needs to be secure in its own right. There is extensive
documentation on securing each of these components and the reader is
encouraged to review this material. For the purpose of this discussion
we are most interested in how Apache and the Java EE
Container cooperate to form an integrated security system. Because
Apache is performing authentication on behalf of the Java EE Container,
it views Apache as a trusted partner. Our primary concern is the
communication channel between Apache and the Java EE Container. We
must assure the Java EE Container knows who it's trusted partner is
and that it only accepts security sensitive data from that partner,
this can best be described as `The Proxy Problem`_.

Forged REMOTE_USER
------------------

HTTP request handling is often implemented as a processing pipeline
where individual handlers are passed the request, they may then attach
additional metadata to the request or transform it in some manner
before handing it off to the next stage in the pipeline. A request
handler may also short circuit the request processing pipeline and
cause a response to be generated. Authentication is typically
implemented an as early stage request handler. If a request gets past
an authentication handler later stage handlers can safely assume the
request belongs to an authenticated user. Authorization metadata may
also have been attached to the request. Later stage handlers use the
authentication/authorization metadata to make decisions as to whether
the operations in the request can be satisfied.

When a request is fielded by a traditional web server with CGI (Common
Gateway Interface, RFC 3875) the request metadata is passed via CGI
meta-variables. CGI meta-variables are often implemented as environment
variables, but in practical terms CGI metadata is really just a set of
name/value pairs a later stage (i.e. CGI script, servlet, etc.) can
reference to learn information about the request.

The CGI meta-variables REMOTE_USER and AUTH_TYPE relate to
authentication. REMOTE_USER is the identity of the authenticated user
and AUTH_TYPE is the authentication mechanism that was used to
authenticate the user.

**If a later stage request handler sees REMOTE_USER and AUTH_TYPE as
non-null values it assumes the user is fully authenticated! Therefore
is it essential REMOTE_USER and AUTH_TYPE can only enter the request
pipeline via a trusted source.**

The Proxy Problem
=================

In a traditional monolithic web server the CGI meta-variables are
created and managed by the web server, which then passes them to CGI
scripts and executables in a very controlled environment where they
execute in the context of the web server. Forgery of CGI
meta-variables is generally not possible unless the web server has
been compromised in some fashion.

However in our configuration the Apache web server acts as an identity
processor, which then forwards (i.e. proxies) the request to the Java
EE container (i.e Tomcat, Jetty, etc.). One could think of the Java
EE container as just another CGI script which receives CGI
meta-variables provided by the Apache web server. Where this analogy
breaks down is how Apache invokes the CGI script. Instead of forking a
child process where the child's environment and input/output pipes are
carefully controlled by Apache the request along with its additional
metadata is forwarded over a transport (typically TCP/IP) to another
process, the proxy, which listens on socket.

The proxy (in this case the Java EE container) reads the request and
the attached metadata and acts upon it. If the request read by the
proxy contains the REMOTE_USER and AUTH_TYPE CGI meta-variables the
proxy will consider the request **fully authenticated!**. Therefore
when the Java EE container is configured as a proxy it is
**essential** it only reads requests from a **trusted** Apache web
server. If any other client aside from the trusted Apache web server
is permitted to connect to the Java EE container that client could
present forged REMOTE_USER and AUTH_TYPE meta-variables, which would be
automatically accepted as valid thus opening a huge security hole.


Possible Approaches to Lock Down a Proxy Channel
================================================

Tomcat Valves
-------------

You can use a `Tomcat Remote Address Valve`_ valve to filter by IP or
hostname to only allow a subset of machines to connect. This can be
configured at the Engine, Host, or Context level in the
conf/server.xml by adding something like the following:

::

  <!-- allow only LAN IPs to connect -->
  <Valve className="org.apache.catalina.valves.RemoteAddrValve"
   allow="192.168.1.*">
  </Valve>

The problem with valves is they are a Tomcat only concept, the
``RemoteAddrValve`` only checks addresses, not port numbers (although
it should be easy to add port checking) and they don't offer anything
better than what is described in `Locking Down the Apache to Java EE
Container Channel`_, which is not container specific. Servlet filters
are always available regardless of the container the servlet is
running in. A filter can check both the address and port number and
refuse to operate on the request if the address and port are not known to
be a trusted authentication proxy. Also note that if the Java EE
Container is configured to accept connections other than from the
trusted HTTP proxy server (a very likely scenario) then filtering at
the connector level is not sufficient because a servlet which trusts
``REMOTE_USER`` must be assured the request arrived only on a
trusted HTTP proxy server connection, not one of the other possible
connections.

SSL/TLS with client auth
------------------------

SSL with client authentication is the ultimate way to lock down a HTTP
Server to Java EE Container proxy connection. SSL with client
authentication provides authenticity, integrity, and
confidentiality. However those desirable attributes come at a
performance cost which may be excessive. Unless a persistent TCP
connection is established between the HTTP server and the Java EE
Container a SSL handshake will need to occur on each request being
proxied, SSL handshakes are expensive. Given that the HTTP server and
the Java EE Container will likely be deployed on the same compute node
(or at a minimum on a secure subnet) the advantage of SSL for proxy
connections may not be warranted because other options are available
for these configuration scenarios; see `Locking Down the Apache to Java EE
Container Channel`_. Also note that if the Java EE
Container is configured to accept connections other than from the
trusted HTTP proxy server (a very likely scenario), then filtering at
the connector level is not sufficient because a servlet which trusts
``REMOTE_USER`` must be assured that the request arrived only on a
trusted HTTP proxy server connection, not one of the other possible
connections.


Java Security Manager Permissions
---------------------------------

The Java Security Manager allows you define permissions which are
checked at run time before code executes.
``java.net.SocketPermission`` and ``java.net.NetPermission`` would
appear to offer solutions for restricting which host and port a
request containing ``REMOTE_USER`` will be trusted. However security
permissions are applied *after* a request is accepted by a
connector. They are also more geared towards what connections code can
subsequently utilize as opposed to what connection a request was
presented on. Therefore security manager permissions seem to offer little
value for our purpose. One can simply test to see which host sent the
proxy request and on what port it arrived on by looking at the
connection information in the request. Restricting which proxies can
submit trusted requests is better handled at the level of the
connector, which unfortunately is a container implementation
issue. Tomcat and Jetty have different ways of handling connector
specifications.

AJP requiredSecret
------------------

The AJP protocol includes an attribute called ``requiredSecret``, which
can be used to secure the connection between AJP endpoints. When an
HTTP server sends an AJP proxy request to a Java EE Container it
embeds in the protocol transmission a string (``requiredSecret``)
known only to the HTTP server and the Java EE Container. The AJP
connector on the Java EE Container is configured with the
``requiredSecret`` value and will reject as unauthorized any AJP
requests whose ``requiredSecret`` does not match.

There are two problems with `requiredSecret``. First of all it's not
particularly secure. In fact, it's fundamentally no different than
sending a cleartext password. If the AJP request is not encrypted it
means the ``requiredSecret`` will be sent in the clear which is
probably one of the most egregious security mistakes. If the AJP
request is transmitted in a manner where the traffic can be sniffed, it
would be trivial to recover the ``requiredSecret`` and forge a request
with it. On the other hand encrypting the communication channel
between the HTTP server and the Java EE Container means using SSL
which is fairly heavyweight. But more to the point, if one is using
SSL to encrypt the channel there is a *far better* mechanism to ensure
the HTTP server is who it claims to be than embedding
``requiredSecret``. If one is using SSL you might as well use SSL
client authentication where the HTTP identifies itself via a client
certificate. SSL client authentication is a very robust authentication
mechanism. But doing SSL client authentication, or for that matter
just SSL encryption, for *every* AJP protocol request is prohibitively
expensive from a performance standpoint.

The second problem with ``requiredSecret`` is that despite being documented
in a number of places it's not actually implemented in Apache
``mod_proxy_ajp``. This is detailed in `bug 53098`_. You can set
``requiredSecret`` in the ``mod_proxy_ajp`` configuration, but it won't
be included in the wire protocol. There is a patch to implement
``requiredSecret`` but, it hasn't made it into any shipping version of
Apache yet. But even if ``requiredSecret`` was implemented it's not
useful. Also one could construct the equivalent of ``requiredSecret``
from other AJP attributes and/or an HTTP extension header but those
would suffer from the same security issues ``requiredSecret`` has,
therefore it's mostly pointless.

Java EE Container Issues
========================

Jetty Issues
------------

Jetty is a Java EE Container which can be used
as alternative to Tomcat. Jetty is an Eclipse project. Recent versions
of Jetty have dropped support for AJP; this is described in the
`Jetty AJP Configuration Guide`_ which states:

  Configuring AJP13 Using mod_jk or mod_proxy_ajp. Support for this
  feature has been dropped with Jetty 9.  If you feel this should be
  brought back please file a bug.

Eclipse `Bug 387928`_ *Retire jetty-ajp* was opened to track the
removal of AJP in Jetty and is now closed.

Tomcat Issues
-------------

You should refer the `Tomcat Security How-To`_ for a full discussion
of Tomcat security issues.

The tomcatAuthentication attribute is used with the AJP connectors to
determine if Tomcat should authenticate the user or if authentication
can be delegated to the reverse proxy that will then pass the
authenticated username to Tomcat as part of the AJP protocol.

The requiredSecret attribute in AJP connectors configures a shared
secret between Tomcat and the reverse proxy in front of Tomcat. It is used
to prevent unauthorized connections over AJP protocol.

Locking Down the Apache to Java EE Container Channel
====================================================

The recommended approach to lock down the proxy channel is:

  * Run both Apache and the servlet container on the same host.

  * Configure Apache to forward the proxy request on the loopback
    interface (e.g. 127.0.0.1 also known as ``localhost``). This
    prohibits any external IP address from connecting, only processes
    running on the locked down host can communicate over
    ``localhost``.

  * Reserve one or more ports for communication **exclusively** for
    proxy communication between Apache and the servlet container. The
    servlet container may listen on other ports for non-critical
    non-authenticated requests.

  * The ``ClaimAuthFilter`` that reads the identity metadata **must**
    assure that requests have arrived only on a **trusted port**. To
    achieve this the ``FederationConfiguration`` defines the
    ``secureProxyPorts`` configuration option. ``secureProxyPorts`` is
    a space delimited list of ports which during deployment the
    administrator has configured such that they are **exclusively**
    dedicated for use by the Apache server(s) providing authentication
    and identity information. These ports are set in the servlet
    container's ``Connector`` declarations. See `Declaring the
    Connector Ports for Authentication Proxies`_ for more
    information).

  * When the ``ClaimAuthFilter`` receives a request, the first thing
    it does is check the ``ServletRequest.getLocalPort()`` value and
    verifies it is a member of the ``secureProxyPorts`` configuration
    option. If the port is a member of ``secureProxyPorts``, it will
    trust every identity assertion found in the request. If the local
    port is not a member of ``secureProxyPorts``, a HTTP 401
    (unauthorized) error status will be returned for the request. A
    warning message will be logged the first time this occurs.


Declaring the Connector Ports for Authentication Proxies
--------------------------------------------------------

As described in `The Proxy Problem`_ the AAA authentication system
**must** confirm the request it is processing originated from a *trusted
HTTP proxy server*. This is accomplished with port isolation.

The administrator deploying a federated AAA solution with SSSD
identity lookups must declare in the AAA federation configuration
which ports the proxy requests from the trusted HTTP server will
arrive on by setting the ``secureProxyPorts`` configuration
item. These ports **must** only be used for the trusted HTTP proxy
server. The AAA federation software will not perform authentication
for any request arriving on a port other than those listed in
``secureProxyPorts``.

.. figure:: sssd_05.png
   :align: center

   _`Figure 5.`

``secureProxyPorts`` configuration option is set either in the
``federation.cfg`` file or in the
``org.opendaylight.aaa.federation.secureProxyPorts`` bundle
configuration. ``secureProxyPorts`` is a space-delimited list of port
numbers on which a trusted HTTP proxy performing authentication
forwards pre-authenticated requests. For example:

::

  secureProxyPorts=8383

Means a request which arrived on port 8383 is from a trusted HTTP
proxy server and the value of ``REMOTE_USER`` and other authentication
metadata in request can be trusted.

########
Appendix
########

*****************
CGI Export Issues
*****************

Apache processes requests as a series of steps in a pipeline
fashion. The ordering of these steps is important. Core Apache is
fairly minimal, most of Apache's features are supplied by loadable
modules. When a module is loaded it registers a set of *hooks*
(function pointers) which are to be run at specific stages in the
Apache request processing pipeline. Thus a module can execute code at
any of a number of stages in the request pipeline.

The user metadata supplied by Apache is initialized in two distinct
parts of Apache.

  1. an authentication module (e.g. mod_auth_kerb)
  2. the ``mod_lookup_identity`` module.

After successful authentication the authentication module will set the
name of the user principal and the mechanism used for authentication
in the request structure.

  * ``request->user``
  * ``request->ap_auth_type``

Authentication hooks run early in the request pipeline for the obvious
reason a request should not be processed if not authenticated. The
specific authentication module that runs is defined by ``Location``
directive in the Apache configuration which binds specific
authentication to specific URL's. The ``mod_lookup_identity`` module
must run *after* authentication module runs because it depends on
knowing who the authenticated principal is so it can lookup the data
on that principal.

When reading ``mod_lookup_identity`` documentation one often sees
references to the ``REMOTE_USER`` CGI environment variable with the
implication ``REMOTE_USER`` is how one accesses the name of the
authenticated principal. This is a bit misleading, ``REMOTE_USER`` is
a CGI environment variable. CGI environment variables are only set by
Apache when it believes the request is going to be processed by a CGI
implementation. In this case ``REMOTE_USER`` is initialized from the
``request->user`` value.

How is the authenticated principal actually forwarded to our proxy?
===================================================================

If we are using the AJP proxy protocol the ``mod_proxy_ajp`` module
when preparing the proxy request will read the value of
``request->user`` and insert it into the ``SC_A_REMOTE_USER`` AJP
attribute. On the receiving end ``SC_A_REMOTE_USER`` will be extracted
from the AJP request and used to populate the value returned
by``HttpServletRequest.getRemoteUser()``. The exchange of the
authenticated principal when using AJP is transparent to both the
sender and receiver, nothing special needs to be done. See
`Transporting Identity Metadata from Apache to a Java EE Servlet`_
for details on how metadata can be exchanged with the proxy.

However, if AJP is not being used to proxy the request the
authenticated principal must be passed through some other mechanism,
an HTTP extension header is the obvious solution. The Apache
``mod_headers`` module can be used to add HTTP request headers to the
proxy request, for example:

::

  RequestHeader set MY_HEADER MY_VALUE

Where does the value MY_VALUE come from? It can be hardcoded into the
``RequestHeader`` statement or it can reference an existing
environment variable like this:

::

  RequestHeader set MY_HEADER %{FOOBAR}e

where the notation ``%{FOOBAR}e`` is the contents of the environment
variable FOOBAR. Thus we might expect we could do this:

::

  RequestHeader set REMOTE_USER %{REMOTE_USER}e

The conundrum is the presumption the ``REMOTE_USER`` environment
variable has already been set at the time ``mod_headers`` executes the
``RequestHeader`` statement. Unfortunately this often is not the
case.

The Apache environment variables ``REMOTE_USER`` and ``AUTH_TYPE`` are
set by the Apache function ``ap_add_common_vars()`` defined in
server/util_script.c.  ``ap_add_common_vars()`` and is called by the
following modules:

  * mod_authnz_fcgi
  * mod_proxy_fcgi
  * mod_proxy_scgi
  * mod_isapi
  * mod_ext_filter
  * mod_include
  * mod_cgi
  * mod_cgid

Apache variables
================

Apache modules provide access to variables which can be referenced by
configuration directives. Unfortunately there isn't a lot of
uniformity to what the variables are and how they're referenced; it
mostly depends on how a given Apache module was implemented. As you
might imagine a bit of inconsistent historical cruft has accumulated
over the years, it can be confusing. The Apache Foundation is trying
to clean some of this up bringing uniformity to modules by utilizing
the common ``expr`` (expression) module `ap_expr`_. The idea being modules will
forgo their home grown expression syntax with its numerous quirks and
instead expose the common ``expr`` language. However this is a work in
progress and at the time of this writing only a few modules have acquired
``expr`` expression support.

Among the existing Apache modules there currently are three different
sets of variables.

  1. Server variables.
  2. Environment variables.
  3. SSL variables.

Server variables (item 1) are names given to internal values. The set
of names for server variables and what they map to are defined by the
module implementing the server variable lookup. For example
``mod_rewrite`` has its own variable lookup implementation.

Environment variables (item 2) are variables *exported* to a
subprocess. Internally they are stored in
``request->subprocess_env``. The most common use of environment
variables exported to a subprocess are the CGI variables.

SSL variables are connection specific values describing the SSL
connection. The lookup is implemented by ``ssl_var_lookup()``, which
given a variable name looks in a variety of internal data structures to
find the matching value.

The important thing to remember is **server variables != environment
variables**. This can be confusing because they often share the same
name. For example, there is the server variable ``REMOTE_USER`` and
there is the environment variable ``REMOTE_USER``. The environment
variable ``REMOTE_USER`` only exists if some module has called
``ap_add_common_vars()``. To complicate matters, some modules allow you
to access *server variables*, other modules allow you to access
*environment variables* and some modules provide access to both
*server variables* and *environment variables*.

Coming back to our goal of setting an HTTP extension header to the
value of ``REMOTE_USER``, we observe that ``mod_headers`` provides the
needed ``RequestHeader`` operation to set a HTTP header in the
request. Looking at the documentation for ``RequestHeader`` we see a
value can be specified with one of the following lookups:

%{VARNAME}e
  The contents of the environment variable VARNAME.

%{VARNAME}s
  The contents of the SSL environment variable VARNAME, if mod_ssl is enabled.

But wait! This only gives us access to *environment variables* and the
``REMOTE_USER`` environment variable is only set if
``ap_add_common_vars()`` is called by a module **after** an
authentication module runs! ``ap_add_common_vars()`` is usually only
invoked if the request is going to be passed to a CGI script. But
we're not doing CGI; instead we're proxying the request. The
likelihood the ``REMOTE_USER`` environment variable will be set is
quite low. See `Setting the REMOTE_USER environment variable`_.

``mod_headers`` is the only way to set a HTTP extension header and
``mod_headers`` only gives you access to environment variables and the
``REMOTE_USER`` environment variable is not set. Therefore if we're
not using AJP and must depend on setting a HTTP extension header for
``REMOTE_USER``, we have a **serious problem**.

But there is a solution; you can either try the machinations described
in `Setting the REMOTE_USER environment variable`_ or assure you're
running at least Apache version 2.4.10. In Apache 2.4.10 the
``mod_headers`` module added support for `ap_expr`_. `ap_expr`_
provides access to *server variables* by using the ``%{VARIABLE}``
notation. `ap_expr`_ also can lookup subprocess environment variables
and operating system environment variables using its ``reqenv()`` and
``osenv()`` functions respectively.

Thus the simple solution for exporting the ``REMOTE_USER`` HTTP
extension header if you're running Apache 2.4.10 or later is:

::

  RequestHeader set X-SSSD-REMOTE_USER expr=%{REMOTE_USER}

The ``expr=%{REMOTE_USER}`` in the above statement says pass
``%{REMOTE_USER}`` as an expression to `ap_expr`_, evaluate the
expression and return the value. In this case the expression
``%{REMOTE_USER}`` is very simple, just the value of the server
variables ``REMOTE_USER``. Because ``RequestHeader`` runs after
authentication ``request->user`` will have been set.

Setting the REMOTE_USER environment variable
============================================

If you do a web search on how to export ``REMOTE_USER`` in a HTTP
extension header for a proxy you will discover this is a common
problem that has frustrated a lot of people [2]_. The usual advice seems to
be to use ``mod_rewrite`` with a look-ahead. In fact this is even
documented in the `mod_rewrite documentation for REMOTE_USER`_ which says:

  %{LA-U:variable} can be used for look-aheads which perform an
  internal (URL-based) sub-request to determine the final value of
  variable. This can be used to access variable for rewriting which is
  not available at the current stage, but will be set in a later
  phase.

  For instance, to rewrite according to the REMOTE_USER variable from
  within the per-server context (httpd.conf file) you must use
  %{LA-U:REMOTE_USER} - this variable is set by the authorization
  phases, which come after the URL translation phase (during which
  mod_rewrite operates).

One suggested solution is this:

::

  RewriteCond %{LA-U:REMOTE_USER} (.+)
  RewriteRule .* - [E=RU:%1]
  RequestHeader set X_REMOTE_USER %{RU}e

1. The RewriteCond with the %{LA-U:} construct performs an internal
   redirect to obtain the value of ``REMOTE_USER`` *server variable*,
   if that value is non-empty because the (.+) regular expression
   matched the rewrite condition succeeds and the following
   RewriteRule executes.

2. The RewriteRule executes, the first parameter is a pattern, the
   second parameter is the replacement which can be followed by
   optional flags inside brackets. The .* pattern is a regular
   expression that matches anything, the - replacement is a special
   value which indicates no replacement is to be performed. In other
   words the pattern and replacement are no-ops and the RewriteRule is
   just being used for it's side effect defined in the flags. The
   E=NAME:VALUE notation says set the NAME environment variable to
   VALUE. In this case the environment variable is RU and the value is
   %1. The documentation for RewriteRule tells us that %N are
   back-references to the last matched RewriteCond pattern, in this
   case it's the value of ``REMOTE_USER``.

3. Finally ``RequestHeader`` sets the request header
   ``X_REMOTE_USER`` to the value of the ``RU`` environment variable.

Another suggested solution is this:

::

  RewriteRule .* - [E=REMOTE_USER:%{LA-U:REMOTE_USER}]

The Problem with mod_rewrite lookahead
--------------------------------------

I **do not recommend** using mod_rewrite's lookahead to gain access to
authentication data values. Although the above suggestions will work
to get access to ``REMOTE_USER`` it is *extremely inefficient* because
it causes Apache to reprocess the request with an internal
redirect. The documentation suggests a lookahead reference will cause
one internal redirect. However from examining Apache debug logs the
``mod_rewite`` lookahead caused ``mod_lookup_identity`` to be invoked
**11 times** while handling one request. If the ``mod_rewrite``
lookahead is removed and another technique is used to get access to
``REMOTE_USER`` then ``mod_lookup_identity`` is invoked exactly once
as expected.

But it's not just ``REMOTE_USER`` which we need access to, we also need
to reference ``AUTH_TYPE`` which has the identical issues associated
with ``REMOTE_USER``. If an equivalent ``mod_rewrite`` block is added
to the configuration for ``AUTH_TYPE`` so that both ``REMOTE_USER``
and ``auth_type`` are resolved using a lookahead Apache appears to go
into an infinite loop and the request stalls.

I tried to debug what was occurring when Apache was configured this way
and why it seemed to be executing the same code over and over but I
was not able to figure it out. My conclusion is **using mod_rewrite
lookahead's is not a viable solution!** Other web posts also make
reference to the inefficiency but they seem to be unaware of just how
bad it is.

.. [1]
   Tomcat has a bug/feature, not all attributes are enumerated by
   getAttributeNames() therefore getAttributeNames() cannot be used to
   obtain the full set of attributes. However if you know the name of
   the attribute a priori you can call getAttribute() and obtain the
   value. Therefore we maintain a list of attribute names
   (httpAttributes) which will be used to call getAttribute() with so we
   don't miss essential attributes.

   This is the Tomcat bug, note it is marked WONTFIX. Bug 25363 -
   request.getAttributeNames() not working properly Status: RESOLVED
   WONTFIX https://issues.apache.org/bugzilla/show_bug.cgi?id=25363

   The solution adopted by Tomcat is to document the behavior in the
   "The Apache Tomcat Connector - Reference Guide" under the JkEnvVar
   property where is says:

   You can retrieve the variables on Tomcat as request attributes via
   request.getAttribute(attributeName). Note that the variables send via
   JkEnvVar will not be listed in request.getAttributeNames().

.. [2]
   Some examples of posts concerning the export of ``REMOTE_USER``  include:
   http://www.jaddog.org/2010/03/22/how-to-proxy-pass-remote_user/ and
   http://serverfault.com/questions/23273/apache-proxy-passing-on-remote-user-to-backend-server/

.. [3]
   The ``mod_lookup_identity`` ``LookupUserGroups`` option accepts an
   optional parameter to specify the separator used to separate group
   names. By convention this is normally the colon (:) character. In
   our examples we explicitly specify the colon separator because the
   mapping rules split the value found in ``REMOTE_USER_GROUPS`` on
   the colon character.

.. [4]
   The example of using the `The Mapping Rule Processor`_ to establish
   the set of roles assigned to a user based on group membership is
   for illustrative purposes in order to show features of the
   federated IdP and mapping mechanism. Role assignment in AAA may be
   done in other ways. For example an unscoped token without roles can
   be used to acquire a scoped token with roles by presenting it to
   the appropriate REST API endpoint. In actual deployments this may
   be preferable because it places the responsibility of deciding who
   has what role/permission on what part of the controller/network
   resources more in the hands of the SDN controller administrator
   than the IdP administrator.

.. _FreeIPA: http://www.freeipa.org/

.. _SSSD: https://fedorahosted.org/sssd/

.. _mod_identity_lookup: http://www.adelton.com/apache/mod_lookup_identity/

.. _AJP: http://tomcat.apache.org/connectors-doc/ajp/ajpv13a.html

.. _Tomcat Security How-To: http://tomcat.apache.org/tomcat-7.0-doc/security-howto.html

.. _The Apache Tomcat Connector - Generic HowTo: http://tomcat.apache.org/connectors-doc/generic_howto/printer/proxy.html

.. _CGI RFC: http://www.ietf.org/rfc/rfc3875

.. _ap_expr: http://httpd.apache.org/docs/current/expr.html

.. _mod_rewrite documentation for REMOTE_USER: http://httpd.apache.org/docs/current/mod/mod_rewrite.html#rewritecond

.. _bug 53098: https://issues.apache.org/bugzilla/show_bug.cgi?id=53098

.. _Jetty AJP Configuration Guide: http://wiki.eclipse.org/Jetty/Howto/Configure_AJP13

.. _Bug 387928: https://bugs.eclipse.org/bugs/show_bug.cgi?id=387928

.. _Tomcat Remote Address Valve: http://tomcat.apache.org/tomcat-7.0-doc/config/valve.html#Remote_Address_Filter