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).

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]).

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/

<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>

<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>

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"
/>

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>

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.

Pseudo Code Illustrating Operational Model

mapped = null
foreach rule in rules {
    result = null
    initialize rule.variables with pre-defined values

    foreach block in rule.statement_blocks {
        for statement in block.statements {
            if statement.verb is exit {
                result = exit.status
                break
            }
            elif statement.verb is continue {
                break
            }
        }
        if result {
            break
        }
    if result == null {
        result = success
    }
if result == success {
    mapped = rule.mapping(rule.variables)
}
return mapped

Mapping

A mapping template is used to produce the final associative array of name/value pairs. The template is a JSON Object. The value in a name/value pair can be a constant or a variable. If the template value is a variable the value of the variable is retrieved from the set of local variables bound to the rule thereby replacing it in the final result.

For example given this mapping template and rule variables in JSON:

template:

{
    "organization": "BigCorp.com",
    "user: "$subject",
    "roles": "$roles"
}

local variables:

{
    "subject": "Sally",
    "roles": ["user", "admin"]
}

The final mapped results would be:

{
    "organization": "BigCorp.com",
    "user: "Sally",
    "roles": ["user", "admin"]
}

Each rule must bind a mapping template to the rule. The mapping template may either be defined directly in the rule via the mapping key or referenced by name via the mapping_name key.

If the mapping_name is specified the mapping is looked up in a table of mapping templates bound to the Rule Processor. Using the name of a mapping template is useful when many rules generate the exact same template values.

If both mapping and mapping_name are defined the locally bound mapping takes precedence.

Syntax

The logic for a rule consists of a sequence of statements grouped in blocks. A statement is similar to a function call in a programming language.

A statement is a list of values the first of which is a verb which defines the operation the statement will perform. Think of the verbs as function names or operators. Following the verb are parameters which may be constants or variables. If the statement assigns a value to a variable left hand side of the assignment (lhs) is always the first parameter following the verb in the list of statement values.

For example this statement in JSON:

["split", "$groups", "$assertion[Groups]", ":"]

will assign an array to the variable $groups. It looks up the string named Groups in the assertion which is a colon (:) separated list of group names splitting that string on the colon character.

Statements must be grouped together in blocks. Therefore a rule is a sequence of blocks and block is a sequence of statements. The purpose of blocks is allow for crude flow of control logic. For example this JSON rule has 4 blocks.

[
    [
        ["set", $user, ""],
        ["set", $roles, []]
    ],
    [
        ["in", "UserName", "$assertion"],
        ["continue", "if_not_success"],
        ["set", "$user", "$assertion[UserName"],
    ],
    [
        ["in", "subject", "$assertion"],
        ["continue", "if_not_success"],
        ["set", "$user", "$assertion[subject]"],
    ],
    [
        ["length", "$temp", "$user"],
        ["compare", "$temp", ">", 0],
        ["exit", "rule_fails", "if_not_success"]
        ["append" "$roles", "unprivileged"]
    ]
]

The rule will succeed if either UserName or subject is defined in the assertion and if so the local variable $user will be set to the value found in the assertion and the "unprivileged" role will be appended to the roles array.

The first block performs initialization. The second block tests to see if the assertion has the key UserName if not execution continues at the next block otherwise the value of UserName in the assertion is copied into the variable $user. The third block performs a similar operation looking for a subject in the assertion. The fourth block checks to see if the $user variable is empty, if it is empty the rule fails because it didn't find either a UserName nor a subject in the assertion. If $user is not empty the "unprivileged" role is appended and the rule succeeds.

Data Types

There are 7 supported types which equate to the types available in JSON. At the time of this writing there are 2 implementations of this Mapping specification, one in Python and one in Java. This table illustrates how each data type is represented. The first two columns are definitions from an abstract specification. The JSON column enumerates the data type JSON supports. The Mapping column lists the 7 enumeration names used by the Mapping implemenation in each language. The following columns list the concrete data type used in that language.

Rule Debugging and Documentation

If the rule processor reports an error or if you're debugging your rules by enabling DEBUG log tracing then you must be able to correlate the reported statement to where it appears in your rule JSON source. A message will always identify a statement by the rule number, block number within that rule and the statement number within that block. However once your rules become moderately complex it will become increasingly difficult to identify a statement by counting rules, blocks and statements.

A better approach is to tag rules and blocks with a name or other identifying string. You can set the Reserved Variables rule_name and block_name to a string of your choice. These strings will be reported in all messages along with the rule, block and statement numbers.

JSON does not permit comments, as such you cannot include explanatory comments next to your rules, blocks and statements in the JSON source. The rule_name and block_name can serve a similar purpose. By putting assignments to these variables as the first statement in a block you'll both document your rules and be able to identify specific statements in log messages.

During rule execution the rule_name and block_name are initialized to the empty string at the beginning of each rule and block respectively.

The above example is augmented to include this information. The rule name is set in the first statement in the first block.

[
    [
        ["set", "$rule_name", "Must have UserName or subject"],
        ["set", "block_name", "Initialization"],
        ["set", $user, ""],
        ["set", $roles, []]
    ],
    [
        ["set", "block_name", "Test for UserName, set $user"],
        ["in", "UserName", "$assertion"],
        ["continue", "if_not_success"],
        ["set", "$user", "$assertion[UserName"],
    ],
    [
        ["set", "block_name", "Test for subject, set $user"],
        ["in", "subject", "$assertion"],
        ["continue", "if_not_success"],
        ["set", "$user", "$assertion[subject]"],
    ],
    [
        ["set", "block_name", "If not $user fail, else append unprivileged to roles"],
        ["length", "$temp", "$user"],
        ["compare", "$temp", ">", 0],
        ["exit", "rule_fails", "if_not_success"]
        ["append" "$roles", "unprivileged"]
    ]
]

Variables

Variables always begin with a dollar sign ($) and are followed by an identifier which is any alpha character followed by zero or more alphanumeric or underscore characters. The variable may optionally be delimited with braces ({}) to separate the variable from surrounding text. Three types of variables are supported:

• scalar
• array (indexed by zero based integer)
• associative array (indexed by string)

Both arrays and associative arrays use square brackets ([]) to specify a member of the array. Examples of variable usage:

$name
${name}
$groups[0]
${groups[0]}
$properties[key]
${properties[key]}

An array or an associative array may be referenced by it's base name (omitting the indexing brackets). For example the associative array array named "properties" is referenced using it's base name $properties but if you want to access a member of the "properties" associative array named "duration" you would do this $properties[duration]

This is not a general purpose language with full expression syntax. Only one level of variable lookup is supported. Therefore compound references like this

$properties[$groups[2]]

will not work.

Reserved Variables

A rule has the following reserved variables:

assertion

The current assertion values from the federated IdP. It is a dictionary of key/value pairs.

regexp_array

The regular expression groups from the last successful regexp match indexed by number. Group 0 is the entire match. Groups 1..n are the corresponding parenthesized group counting from the left. For example regexp_array[1] is the first group.

regexp_map

The regular expression groups from the last successful regexp match indexed by group name.

rule_number

The zero based index of the currently executing rule.

rule_name

The name of the currently executing rule. If the rule name has not been set it will be the empty string.

block_number

The zero based index of the currently executing block within the currently executing rule.

block_name

The name of the currently executing block. If the block name has not been set it will be the empty string.

statement_number

The zero based index of the currently executing statement within the currently executing block.

Split a fully qualified username into user and realm components

It's common for some IdP's to return a fully qualified username (e.g. principal or subject). The fully qualified username is the concatenation of the user name, separator and realm name. A common separator is the @ character. In this example lets say the fully qualified username is bob@example.com and you want to return the user and realm as independent values in your mapped result. The username appears in the assertion as the value Principal.

Our strategy will be to use a regular expression identify the user and realm components and then assign them to local variables which will then populate the mapped result.

The mapping in JSON is:

{
    "user": "$username",
    "realm": "$domain"
}

The assertion in JSON is:

{
    "Principal": "bob@example.com"
}

Our rule is:

[
    [
        ["in", "Principal", "assertion"],
        ["exit", "rule_fails", "if_not_success"],
        ["regexp", "$assertion[Principal]", (?P<username>\\w+)@(?P<domain>.+)"],
        ["set", "$username", "$regexp_map[username]"],
        ["set", "$domain", "$regexp_map[domain]"],
        ["exit, "rule_succeeds", "always"]
    ]
]

Rule explanation:

Block 0:

0. Test if the assertion contains a Principal value.
1. Abort the rule if the assertion does not contain a Principal value.
2. Apply a regular expression the the Principal value. Use named groupings for the username and domain components for clarity.
3. Assign the regexp group username to the $username local variable.
4. Assign the regexp group domain to the $domain local variable.
5. Exit the rule, apply the mapping, return the mapped values. Note, an explicit exit is not required if there are no further statements in the rule, as is the case here.

The mapped result in JSON is:

{
    "user": "bob",
    "realm": "example.com"
}

Build a set of roles based on group membership

Often one wants to grant roles to a user based on their membership in certain groups. In this example let's say the assertion contains a Groups value which is a colon separated list of group names. Our strategy is to split the Groups assertion value into an array of group names. Then we'll test if a specific group is in the groups array, if it is we'll add a role. Finally if no roles have been mapped we fail. Users in the group "student" will get the role "unprivileged" and users in the group "helpdesk" will get the role "admin".

The mapping in JSON is:

{
    "roles": "$roles",
}

The assertion in JSON is:

{
    "Groups": "student:helpdesk"
}

Our rule is:

[
    [
        ["in", "Groups", "assertion"],
        ["exit", "rule_fails", "if_not_success"],
        ["set", "$roles", []],
        ["split", "$groups", "$assertion[Groups]", ":"],
    ],
    [
        ["in", "student", "$groups"],
        ["continue", "if_not_success"],
        ["append", "$roles", "unprivileged"]
    ],
    [
        ["in", "helpdesk", "$groups"],
        ["continue", "if_not_success"],
        ["append", "$roles", "admin"]
    ],
    [
        ["unique", "$roles", "$roles"],
        ["length", "$temp", "roles"],
        ["compare", $temp", ">", 0],
        ["exit", "rule_fails", "if_not_success"]
    ]

]

Rule explanation:

Block 0

0. Test if the assertion contains a Groups value.
1. Abort the rule if the assertion does not contain a Groups value.
2. Initialize the $roles variable to an empty array.
3. Split the colon separated list of group names into an array of individual group names

Block 1

0. Test if "student" is in the $groups array
1. Exit the block if it's not.
2. Append "unprivileged" to the $roles array

Block 2

0. Test if "helpdesk" is in the $groups array
1. Exit the block if it's not.
2. Append "admin" to the $roles array

Block 3

0. Strip any duplicate roles that might have been appended to the $roles array to assure each role is unique.
1. Count how many members are in the $roles array, assign the length to the $temp variable.
2. Test to see if the $roles array had any members.
3. Fail if no roles had been assigned.

The mapped result in JSON is:

{
    "roles": ["unprivileged", "admin"]
}

However, suppose whatever is receiving your mapped results is not expecting an array of roles. Instead it expects a comma separated list in a string. To accomplish this add the following statement as the last one in the final block:

["join", "$roles", "$roles", ","]

Then the mapped result will be:

{
    "roles": "unprivileged,admin"]
}

White list certain users and grant them specific roles

Suppose you have certain users you always want to unconditionally accept and authorize with specific roles. For example if the user is "head_of_IT" then assign her the "user" and "admin" roles. Otherwise keep processing. The list of white listed users is hard-coded into the rule.

The mapping in JSON is:

{
    "user": $user,
    "roles": "$roles",
}

The assertion in JSON is:

{
    "UserName": "head_of_IT"
}

Our rule in JSON is:

[
    [
        ["in", "UserName", "assertion"],
        ["exit", "rule_fails", "if_not_success"],
        ["in", "$assertion[UserName]", ["head_of_IT", "head_of_Engineering"]],
        ["continue", "if_not_success"],
        ["set", "$user", "$assertion[UserName"]
        ["set", "$roles", ["user", "admin"]],
        ["exit", "rule_succeeds", "always"]
    ],
    [
        ...
    ]
]

Rule explanation:

Block 0

0. Test if the assertion contains a UserName value.
1. Abort the rule if the assertion does not contain a UserName value.
2. Test if the user is in the hardcoded list of white listed users.
3. If the user isn't in the white listed array then exit the block and continue execution at the next block.
4. Set the $user local variable to $assertion[UserName]
5. Set the $roles local variable to the hardcoded array containing "user" and "admin"
6. We're done, unconditionally exit and return the mapped result.

Block 1

0. Further processing

The mapped result in JSON is:

{
    "user": "head_of_IT",
    "roles": ["users", "admin"]
}

Black list certain users

Suppose you have certain users you always want to unconditionally deny access to by placing them in a black list. In this example the user "BlackHat" will try to gain access. The black list includes the users "BlackHat" and "Spook".

The mapping in JSON is:

{
    "user": $user,
    "roles": "$roles",
}

The assertion in JSON is:

{
    "UserName": "BlackHat"
}

Our rule in JSON is:

[
    [
        ["in", "UserName", "assertion"],
        ["exit", "rule_fails", "if_not_success"],
        ["in", "$assertion[UserName]", ["BlackHat", "Spook"]],
        ["exit", "rule_fails", "if_success"]
    ],
    [
        ...
    ]
]

Rule explanation:

Block 0

0. Test if the assertion contains a UserName value.
1. Abort the rule if the assertion does not contain a UserName value.
2. Test if the user is in the hard-coded list of black listed users.
3. If the test succeeds then immediately abort and return failure.

Block 1

0. Further processing

The mapped result in JSON is:

Null

Format Strings and/or Concatenate Strings

You can replace variables in a format string using the interpolate verb. String concatenation is trivially placing two variables adjacent to one another in a format string. Suppose you want to form an email address from the username and domain in an assertion.

The mapping in JSON is:

{
    "email": $email,
}

The assertion in JSON is:

{
    "UserName": "Bob",
    "Domain": "example.com"
}

Our rule in JSON is:

[
    [
        ["interpolate", "$email", "$assertion[UserName]@$assertion[Domain]"],
    ]
]

Rule explanation:

Block 0

0. Replace the variable $assertion[UserName] with it's value and replace the variable $assertion[Domain] with it's value.

The mapped result in JSON is:

{
    "email": "Bob@example.com",
}

Note, sometimes it's necessary to utilize braces to separate variables from surrounding text by using the brace notation. This can also make the format string more readable. Using braces to delimit variables the above would be:

[
    [
        ["interpolate", "$email", "${assertion[UserName]}@${assertion[Domain]}"],
    ]
]

Make associative array lookups case insensitive

Many systems treat field names as case insensitive. By default associative array indexing is case sensitive. The solution is to lower case all the keys in an associative array and then only use lower case indices. Suppose you want the assertion associative array to be case insensitive.

The mapping in JSON is:

{
    "user": $user,
}

The assertion in JSON is:

{
    "UserName": "Bob"
}

Our rule in JSON is:

[
    [
        ["lower", "$assertion", "$assertion"],
        ["in", "username", "assertion"],
        ["exit", "rule_fails", "if_not_success"],
        ["set", "$user", "$assertion[username"]
    ]
]

Rule explanation:

Block 0

0. Lower case all the keys in the assertion associative array.
1. Test if the assertion contains a username value.
2. Abort the rule if the assertion does not contain a username value.
3. Assign the username value in the assertion to $user

The mapped result in JSON is:

{
    "user": "Bob",
}

set

set $variable value

$variable

The variable being assigned (i.e. lhs)

value

The value to assign to the variable (i.e. rhs). The value may be another variable or a constant.

set assigns a value to a variable, in other words it's an assignment statement.

["set", "$groups", []]

["set", "$groups", {}]

["set", "$version", "1.2.3"]

["set", "$temp", "$assertion[UserName]"],

["set", "$group", "$groups[1]"]

["set", "$metadata[IdP]", "kdc.example.com""]

length

length $variable value

$variable

The variable which receives the length value

value

The value whose length is to be determined. May be one of array, associative array, or string.

length computes the number of items in the value. How this is done depends upon the type of value:

array

The length is the number of items in the array.

associative array

The length is the number of key/value pairs in the associative array.

string

The length is the number of characters (not octets) in the string.

["length", "$groups_length", "$groups"]

["length", "$num_assertion_values", "$assertion"]

["length", "$user_name_length", "$assertion[UserName]"]

interpolate

interpolate $variable string

$variable

This variable is assigned the result of the interpolation.

string

A string containing references to variables which will be replaced in the string.

interpolate replaces each occurrence of a variable in a string with it's value. The result is assigned to $variable.

["interpolate", "$email", "${username}@${domain}"]

append

append $variable value

$variable

This variable must be an array. It is modified in place by appending value to the end of the array.

value

The value to append to the end of the array.

append adds a value to end of an array.

["append", "$roles", "qa_test"]

unique

unique $variable value

$variable

This variable is assigned the unique values in the value array.

value

An array of values. must be an array.

unique builds an array of unique values in value by stripping out duplicates and assigns the array of unique values to $variable. The order of items in the value array are preserved.

["unique", "$one_of_a_kind", ["a", "b", "a"]]

regexp

regexp string pattern

string

The string the regular expression pattern is applied to.

pattern

The regular expression pattern.

regexp performs a regular expression match against string. The regular expression pattern syntax is defined by the regular expression implementation of the language this API is written in.

Pattern groups are a convenient way to select sub-matches. Pattern groups may accessed by either group number or group name. After a successful regular expression match the groups are stored in the special variables $regexp_array and $regexp_map.

$regexp_array is used to access the groups by numerical index. Groups are numbered by counting the left parenthesis group delimiter starting at 1. Group 0 is the entire match. $regexp_array is valid irregardless of whether you used named groups or not.

$regexp_map is used to access the groups by name. $regexp_map is only valid if you used named groups in the pattern.

["regexp", "$assertion[UserName]", "(?P<username>\\w+)@(?P<domain>.+)"],
["continue", "if_not_success"],
["set", "$username", "$regexp_map[username]"],
["set", "$domain", "$regexp_map[domain]"],

["regexp", "$assertion[UserName]", "(\\w+)@(.+)"],
["continue", "if_not_success"],
["set", "$username", "$regexp_array[1]"],
["set", "$domain", "$regexp_array[2]"],

regexp_replace

regexp_replace $variable string pattern replacement

$variable

The variable which receives result of the replacement.

string

The string to perform the replacement on.

pattern

The regular expression pattern.

replacement

The replacement specification.

regexp_replace replaces each occurrence of pattern in $string with replacement. See regexp for details of using regular expressions.

["regexp_replace", "$name", "$name", "-", "_"]

split

split $variable string pattern

$variable

This variable is assigned an array containing the split items.

string

The string to split into separate items.

pattern

The regular expression pattern used to split the string.

split splits string into separate pieces and assigns the result to $variable as an array of pieces. The split occurs wherever the regular expression pattern occurs in string. See regexp for details of using regular expressions.

["split", "$group_list", "$assertion[Groups]", ":"]

join

join $variable array join_string

$variable

This variable is assigned the string result of the join operation.

array

An array of string items to be joined together with $join_string.

join_string

The string inserted between each element in array.

join accepts an array of strings and produces a single string where each element in the array is separated by join_string.

["join", "$group_string", "$groups", ":"]

lower

lower $variable value

$variable

This variable is assigned the result of the lower operation.

value

The value to lower case, may be either a string, array, or associative array.

lower lower cases the input value. The input value may be one of the following types:

string

The string is lower cased.

array

Each member of the array must be a string, the result is an array with the items replaced by their lower case value.

associative array

Each key in the associative array is lower cased. The values associated with the key are not modified.

["lower", "$username", "$assertion[UserName]"],

["lower", "$groups", "$groups"],

["lower", "$assertion", $assertion"]

upper

upper $variable value

$variable

This variable is assigned the result of the upper operation.

value

The value to upper case, may be either a string, array, or associative array.

upper is exactly analogous to lower except the values are upper cased, see lower for details.

in

in member collection

member

The value whose membership is being tested.

collection

A collection of members. May be string, array or associative array.

in tests to see if member is a member of collection. The membership test depends on the type of collection, the following are supported:

array

If any item in the array is equal to member then the result is success.

associative array

If the associative array contains a key equal to member then the result is success.

string

If the string contains a sub-string equal to member then the result is success.

["in", "UserName", "$assertion"]
["continue", "if_not_success"]

["in", "$group", ["user", "admin"]]
["continue", "if_not_success"]

["in", "BigCorp", "$assertion[Provider]"]
["continue", "if_not_success"]

not_in

in member collection

member

The value whose membership is being tested.

collection

A collection of members. May be string, array or associative array.

not_in is exactly analogous to in except the sense of the test is reversed. See in for details.

compare

compare left operator right

left

The left hand value of the binary operator.

operator

The binary operator used for comparing left to right.

right

The right hand value of the binary operator.

compare compares the left value to the right value according the operator and sets success if the comparison evaluates to True. The following relational operators are supported.

The left and right hand sides of the comparison operator must be the same type, no type conversions are performed. Not all combinations of operator and type are supported. The table below illustrates the supported combinations. Essentially you can test for equality or inequality on any type. But only strings and numbers support the magnitude relational operators.

["length", "$group_length", "$groups"],
["compare", "$group_length", ">=", 2]

exit

exit status criteria

status

The result for the rule.

criteria

The criteria upon which will cause the rule will be immediately exited with a failed status.

exit causes the rule being executed to immediately exit and a rule result if the specified criteria is met. Statement verbs such as in or compare set the result status which may be tested with the success and not_success criteria.

The exit status may be one of:

rule_fails

The rule has failed and no mapping will occur.

rule_succeeds

The rule succeeded and the mapping will be applied.

The criteria may be one of:

if_success

If current result status is success then exit with status.

if_not_success

If current result status is not success then exit with status.

always

Unconditionally exit with status.

never

Effectively a no-op. Useful for debugging.

["in", "UserName", "$assertion"]
["exit", "rule_fails", "if_not_success"]

continue

continue criteria

criteria

The criteria which causes the remainder of the block to be skipped.

continue is used to control execution for statement blocks. It mirrors in a crude way the if expression in a procedural language. continue does not affect the success or failure of a rule, rather it controls whether subsequent statements in a block are executed or not. Control continues at the next statement block.

Statement verbs such as in or compare set the result status which may be tested with the success and not_success criteria.

The criteria may be one of:

if_success

If current result status is success then exit the statement block and continue execution at the next statement block.

if_not_success

If current result status is not success then exit the statement block and continue execution at the next statement block.

always

Immediately exit the statement block and continue execution at the next statement block.

never

Effectively a no-op. Useful for debugging. Execution continues at the next statement.

roles = [];
if ("Groups" in assertion) {
    groups = assertion["Groups"].split(":");
    if ("qa_test" in groups) {
        roles.append("tester");
    }
}

[
    ["set", "$roles", []],
    ["in", "Groups", "$assertion"],
    ["continue", "if_not_success"],
    ["split" "$groups", $assertion[Groups]", ":"],
    ["in", "qa_test", "$groups"],
    ["continue", "if_not_success"],
    ["append", "$roles", "tester"]
]

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.

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.

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.

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 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.

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.