Skip to main content
Version: 4.6.x.x LTS

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.
  • parameter_nameDescribes 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_nameThe name of the HTTP header sent to the content provider.
  • encodingUsed 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
  • The format of a list entry is: <source>:<parameter_name>:<trace_name>
  • Describes the HTTP header of the request that will be traced with the trace group NProxyOp on INFO log level.

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 (/), and its prefix must be 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
  • Correct syntax: <source>:<parameter_name>
  • 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.

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.

Kerberos.Policy​

  • Type: enum: NONE, PROACTIVE, CACHE

  • Usage Constraint: optional

  • Default: PROACTIVE

  • Policy how to handle the body of a POST-request or similar.

    • NONE: do nothing. Setting it to NONE assumes that some previous GET-request already did the negotiation.
    • PROACTIVE: Do the renegotiation again, before sending the data. This should work for most backends.
    • CACHE: Cache the request. If the backend needs renegotiation, the body will be sent again.
    Deprecated

    The Kerberos parameters Kerberos.Delegation, Kerberos.ConfigFile and Kerberos.Policy have been deprecated.

Kerberos.Delegation​

  • Type: string
  • Usage Constraint: optional
  • A list of Realms for which kerberos-negotiation has to be done. The syntax for this parameter is <type>/<host>@<realm>. For example: HTTP/[email protected]

Kerberos.ConfigFile​

  • Type: string
  • Usage Constraint: optional
  • Default: /var/opt/<instance>/conf/nevisproxy-krb5.conf
  • Path to the config file for kerberos-negotiation.

Example configuration​

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