DelegationFilter

The main task of the DelegationFilter is to forward additional information to content providers or to subsequent filters and servlets. The DelegationFilter retrieves the additional information from supported sources and adds it to the user's request.

You can propagate the following types of attributes:

• HTTP headers
• Query parameters
• Cookie parameters
• Basic Authorization HTTP headers
• POST requests

You can configure delegation rules for most parameters of the DelegationFilter. A delegation rule has the following syntax:

<source>:<parameter_name>:<delegation_name>[:encoding]

• source: Defines the context of the given parameter. Supported sources are:
  • AUTH: Any parameters returned by the authentication process
  • CONST: Constants
  • ENV: The environment of Apache (CGI-style)
  • RESP: Permits content providers to return an additional value for delegation
  • PARAM: Values from a request/response body processed by the ParameterFilter
  • HEADER: Request headers
  • SESSION: Session attributes
• parameter_name: Describes the name used to retrieve the parameter from the source, or the value of the delegated parameter, if the source is of type CONST
• delegation_name: The name of the HTTP header sent to the content provider.
• encoding: Used to overwrite the default encoding for a rule.

The colon is used as delimiter for the delegation rules. For this reason, it is necessary to escape a colon in the parameter or delegation name with a backslash.

Propagating attributes from nevisAuth

The following attributes from the nevisAuth authentication are available:

• user.auth.UserId
• user.auth.SessionId
• user.auth.Realm
• user.auth.SecurityRoles
• user.auth.SecToken
• user.auth.ClientCert (base64 encoded without newlines)

Refer to the nevisAuth documentation for a repository of global Nevis session attributes (see ch.nevis.session.<name>) and to the authentication plug-in or backend documentation for a list of implementation-specific attributes.

Propagating attributes from the reverse proxy

It is possible to propagate attributes from the reverse proxy context (ENV source). The available attributes depend on the Apache setup and usually include CGI and (if enabled) TLS parameters. To use Apache environment attributes, you may need to enable environment variable support (for example, mod_ssl requires a setting "+StdEnvVars" in the SSLOptions attribute, see the chapter How to set up name-based host) and see the corresponding module documentation: mod_ssl, mod_rewrite.

A wide use of this feature is not recommended, because it may lead to tight system coupling (between reverse proxy and content provider). The table in chapter Environment Variables shows a list of available context parameters (ENV source).

Classname

ch::nevis::isiweb4::filter::delegation::DelegationFilter

Library

libDelegationFilters.so.1

Configuration

Delegate

Type: newline-separated list of delegation rules
Usage Constraint: optional, conditions are allowed

This attribute allows the delegation of a request HTTP header to a backend. The attribute is fail-open. This means that a frontend may set the header as well. The header will not be removed if the DelegationFilter would delegate the same header on a given condition, nor will the connection be closed if a specified attribute could not be delegated due to the condition.

Use the HeaderValidationFilter to make the setup fail-close.

DelegateCookie

Type: newline-separated list of delegation rules
Usage Constraint: optional, conditions are allowed

This attribute allows the delegation a cookie to a backend. Only use this attribute if the CookieManager is configured in the Http(s)ConnectorServlet or CookieCacheFilter between the DelegationFilter and the backend. If no CookieManager is configured, specify the delegation of a cookie with the Delegate attribute.

DelegateQuery

Type: newline-separated list of delegation rules
Usage Constraint: optional, conditions are allowed

Allows the delegation of query parameters in such a way, that the values are passed as query arguments in the request line. For example: ?n1=v1&n2=v2. The default encoding is plain.

DelegateQueryPolicy

Type: enum: INITIAL_ONLY, ALWAYS
Usage Constraint: optional, advanced
Default: ALWAYS

This parameter configures the behavior of the query delegation. The following options are available:
ALWAYS: The delegation takes place on every call.
INITIAL_ONLY: The delegation is done only once (within the user session).

DelegateToProxyLog

Type: newline-separated list
Usage Constraint: optional

Describes the HTTP header of the request that will be traced with the trace group NProxyOp on INFO log level.
The format of a list entry is:
<source>:<parameter_name>:<trace_name>

DelegateBasicAuth

Type: newline-separated list containing two entries
Usage Constraint: optional, basic

The Basic Authorization HTTP header will be assembled from two configured entries.
The first entry is the user ID and the second entry is the password. The entries are similar to those of the Delegate function, but the delegation name is fixed. The form is <source>:<key>. See example below. The header is sent to the backend.

<init-param>
      <param-name>DelegateBasicAuth</param-name>
      <param-value>
            AUTH:user.auth.UserId
            AUTH:user.auth.SecToken
      </param-value>
</init-param>

DelegateOutbound

Type: newline-separated list of delegation rules
Usage Constraint: optional, conditions are allowed

Allows to propagate HTTP response headers to the client. Use this feature carefully. Do not propagate sensitive information like the SecToken.

DelegateSource

Type: String
Usage optional, advanced

Allows the configuration of an IdentityCreationFilter whose state can be retrieved from the session. It is possible to configure several IdentityCreationFilters. The filter names are separated by a space or newline. If the StateKey attribute has been configured in the IdentityCreationFilter, use the name of the StateKey instead of the name of the IdentityCreationFilter.

DelegateSource.Policy

Type: enum: FIRST_FND, ALL, BY_TIME
Usage Constraint: optional
Default: FIRST_FND

Defines the behavior of the DelegateSource keys.
The following options are available:
FIRST_FND: Uses the StateKey that is found first.
ALL: Loops over all DelegateSource keys in the order they are configured.
BY_TIME: Loops over all DelegateSource keys sorted by the time their attributes were set.

DelegateSource.Recursive

Type: boolean
Usage Constraint: optional
Default: false

If set, the attributes of the children of the configured DelegateSource are also handled.

DelegatePOST

Type: Newline-separated list of delegation rules
Usage Constraint: optional, advanced, conditions are allowed

Defines the parameters of the POST login request that will be forwarded to the backend during the authentication phase.

DelegatePostPolicy

Type: enum: compat, sidecall, override, stateless-override
Usage Constraint: optional, advanced
Default: compat

Configures the behavior of the delegation via HTTP POST.
The following options are available:
compat: The first request is overridden by the delegation POST request. The follow-up calls are done as sidecalls.
sidecall: All the delegation POST requests are done as sidecalls. The client request still goes to the backend.
override: The user request is POST-ed with the delegation parameters.
stateless-override: Same as the option "override" but without tracking the state. This means that the delegation happens on each request.

DelegatePostValidStatus

Type: integer, range: 100-599
Usage Constraint: optional, advanced

This attribute allows to configure a check for the status code of the initial response to the POST delegate request. If the POST request is sent as a sidecall (see the DelegatePostPolicy parameter) and the status code does not match the value set here, the original client request will be blocked. In case the DelegatePostPolicy parameter is set to "override", the response status will be overwritten.

DelegatePostResendStatus

Type: integer, range: 100-599
Usage Constraint: optional, advanced

If the status information returned by the content provider during a normal request matches this value, the SAML Browser/POST will be resent to the content provider and the corresponding response will be sent to the client

DelegatePostTarget

Type: string
Usage Constraint: optional, advanced

Configures a POST request to a specific location, such as the URL of a SAML assertion consumer.
The URL must meet the following conditions:
It must start with a slash (/). If the backend is a Http[s]ConnectorServlet with the mappingType configured to pathInfo, then it has to start with the original mapping path of the request.
For example, if the filter is mapped to */myapp/myfilter, possible values for the attribute are:

• /myapp
• /myapp/myfilter
• /myapp/otherpath

The following values are not allowed:

• /otherapp
• otherserver.otherdomain/otherpath

Encoding

Type: enum: PLAIN, BASE64, URLENCODING, TRANSCODE_[encoding]
Usage Constraint: optional
Default: PLAIN

Defines the default encoding for all delegations, except for the DelegateQuery. If you want to use the transcoding option, replace [encoding] with the desired output encoding. For example, if nevisProxy is configured to run in ISO-8859-1 (with the variable user.locale in the bc.properties file) and you set this property to TRANSCODE_UTF-8, the delegated property will be converted from ISO-8859-1 to UTF-8 prior to delegation.

ParseSOAPRequest

Type: boolean
Usage Constraint: optional
Default: true

If set to true, SOAP messages will be parsed and internalized (DOM tree). In all other cases, only string replacements are used to insert/append the WSS header.

DelegateSOAPSubstitutedSecurityHeader

Type: string
Usage Constraint: optional, advanced

In case of a SOAP/WSS request, the SOAP/WSS Security header will be substituted with the value of the specified parameter. See also chapter [DelegationFilter].
The correct syntax is:
<source>:<parameter_name>

SOAPCharacterEncoding

Type: String representing a character encoding, like: ASCII, US-ASCII, ISO_8859-1, ISO-8859-1, latin1, csISOLatin1, UTF-16BE, UTF-16LE, UTF-16, UTF-8, etc
Usage Constraint: optional

Defines the character encoding used to externalize the parsed and modified SOAP message.

AppendAssertionSecurityHeader

Type: boolean
Usage Constraint: optional
Default: false

If set to true, the SAML assertion or the Nevis SecToken is appended to the other security headers (instead of dropping the other headers).

CheckResponseHeaders

Type: boolean
Usage Constraint: optional
Default: false

If set to "true", the system checks that the delegated headers are not returned to the client.

CheckRequestHeaders

Type: boolean
Usage Constraint: optional
Default: true

If set to true, the system checks that the client will not send any header that may have been delegated.

Suppress

Type: List of HTTP request header names, separated by colons
Usage Constraint: optional, advanced security

This attribute enables the blocking of the propagation of HTTP request headers.

SuppressResponseHeader

Type: List of HTTP response header names, separated by colons
Usage Constraint: optional, advanced security

This attribute enables the blocking of the propagation of HTTP response headers.

Example configuration

You can find a sample configuration in the installed nevisProxy package, under examples/various/DelegationFilter_delegate_post.example.