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.
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 request/response body cut with ParameterFilter
HEADER: Request headers, a cleaner way than access headers via ENV
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.
It is possible to propagate attributes from the reverse proxy context and see the corresponding module documentation: http://httpd.apache.org/docs/2.2/mod/mod_ssl.html http://httpd.apache.org/docs/2.2/mod/mod_rewrite.html#EnvVar
A widely use of this feature is not recommended because tight system coupling (between reverse proxy and content provider) may result. The following table shows a list of available context parameters (ENV source):
| Variable name | Description |
|---|---|
HTTP_<Header-Name> | Will get the value of the header <Header-Name> replacing all '_' with '-' in the <Header-Name> (Apache-Header Syntax). |
| REMOTE_ADDR | Gets the remote IP address. |
| REMOTE_USER | The remote user. Will only be set if 'TraceRemoteUser' is set in the specific IdentityCreationFilter. |
| REQUEST_METHOD | The request method. Usually 'POST' or 'GET'. |
| REQUEST_URI | The request URI. |
| REQUEST_URL | The request URL. |
| PATH_INFO | The path info part of the request uri. The value of the path info depends on the mapping of the matched servlet. It is determined like that: requesturi = servlet mapping + pathinfoFor example if the request uri is /path1/path2/path3/path4/and the matching servlet of the request is mapped to '/path1/path2/*', then the path info is set to 'path3/path4/'.This variable has nothing to do with the apache environment variable of the same name. |
| QUERY_STRING | The query string (something like name1=value1&name2=value2...). |
| SERVER_NAME | The server name. |
| SERVER_PROTOCOL | The server protocol, e.g., 'HTTP/1.1'. |
| bcx.servlet.session.SSLCiphersUsed bcx.servlet.connection.SSLCiphersUsed | For TLS/SSL connections only. The cipher that has been used. |
| bcx.servlet.session.SSLSessionId bcx.servlet.connection.SSLSessionId | For TLS/SSL connections only. The TLS/SSL session Id. |
| bcx.servlet.session.SessionCookie bcx.servlet.connection.SessionCookie | The value of the session cookie (if available). |
| bcx.servlet.connection.KeepAlives | The number of KeepAlives. |
| bcx.servlet.session.HttpSessionId | Propagates the HTTP session ID (if available). To further control the propagation of the HTTP session ID, you can use the variables bcx.servlet.session.HttpSessionId.get and bcx.servlet.session.HttpSessionId.getOrCreate (see below). |
| bcx.servlet.session.HttpSessionId.get | Only propagates the HTTP session ID if there is a session. |
| bcx.servlet.session.HttpSessionId.getOrCreate | Always propagates the session ID. If there is no session, the variable creates a session with a session ID. |
| bcx.servlet.session.information.ipB | The IP address of the backend. |
| bcx.servlet.session.information.invS | The name of the matched servlet. |
| bcx.servlet.request.TransferID | The transfer ID. |
| bcx.servlet.request.ThreadCounter | The number of current threads. |
| bcx.servlet.request.HostName | The host name. |
| bcx.servlet.request.Counter | The number of requests. Will only be set if the bc-property 'ch.nevis.navajo.runtime.RequestCounting' is set to true. |
bcx.servlet.request.Header.<Header-Name> | Will get the value of the header <Header-Name>. |
| ch.nevis.nevisproxy.redirect.FormRedirect | Set if an AutoForm-redirect-page is sent to the frontend. This can be used for example by the LuaFilter to create a specific page instead of the standard page created by nevisProxy. |
| ch.nevis.nevisproxy.redirect.FormRedirect.Location | The location to redirect to. It is already html-encoded and is only set if 'ch.nevis.nevisproxy.redirect.FormRedirect' is set. |
| ch.nevis.nevisproxy.redirect.FormRedirect.CharSet | The charset used for the hidden fields. The page should use the same charset (if you use a specific one). It is only set if 'ch.nevis.nevisproxy.redirect.FormRedirect' is set. |
| ch.nevis.nevisproxy.redirect.FormRedirect.HiddenFields | The hidden fields of the form. They are already in html-tags and html-encoded. It is only set if 'ch.nevis.nevisproxy.redirect.FormRedirect' is set. |
| SESSION_ID | The session ID. To further control the propagation of the HTTP session ID, you can use the variables bcx.servlet.session.HttpSessionId.get and bcx.servlet.session.HttpSessionId.getOrCreate (both variables are also described in this table). |
| ch.nevis.session.loginid | The login ID. Will only be set if 'TraceRemoteUser' is set in the specific IdentityCreationFilter. |
<apache-env-key> | An Apache-internal key. To trace all Apache-internal keys, set the following value:ENV:TRACE_APACHE_ENV:JustForLoggingThis will trace all Apache keys in the TraceGroup NavajoRequest:INFO. Don't forget to remove the line 'ENV:TRACE_APACHE_ENV:JustForLogging' from your DelegationFilter after tracing. |
| ch.nevis.navajo.chain.MappedServlet | This attribute contains the name of the matched servlet before the servlet is reached. |
There are several possibilities for propagating these attributes:
- as HTTP headers
- as additional query parameters
- as basic auth HTTP header
- as a POST request
Classname
ch::nevis::isiweb4::filter::delegation::DelegationFilter
Library
libDelegationFilters.so.1
Configuration
| Name | Type, Usage Constraints, Defaults | Description |
|---|---|---|
| AppendAssertionSecurityHeader | boolean default: false | If set to true, the SAML assertion or the Nevis SecToken is appended to the other security headers instead of dropping all the others. |
| CheckResponseHeaders | boolean default: false | If set to true, it is checked that the delegated headers are not returned to the client. |
| CheckRequestHeaders | boolean default: true | If set to true, it is checked that the client will not send any header that may have been delegated. |
| Delegate | newline-separated list of delegation specifications optional, basicdefault: empty list | Describes the HTTP header of the request that will be set in the outgoing request with the specified name.Note: The attribute is fail-open, that means, that a frontend may set the header as well, and 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. The format of a list entry is:<source>:<parametername>:<delegationname>where:<source> is one of "AUTH" or "CONST" or "ENV" or "PARAM" or "HEADER"<parametername> describes the name used to retrieve the parameter from <source> (or the value of the delegated parameter if <source> is of type "CONST")<delegationname> is the name of the HTTP header sent to the content provider. In addition it is possible to add a condition of the form: Condition::<VARIABLE>:<expression>CIDR example: REMOTE_ADDR:CIDR/10.4.12.0/22/ |
| DelegatePOST | string optional, advanced feature default: empty list | Newline-separated list of <source>:<key>:<name>[:<encoding>] that defines an additional POST request that is sent once. In addition it is possible to add a condition of the form: Condition::<VARIABLE>:<expression>CIDR example: REMOTE_ADDR:CIDR/10.4.12.0/22/ |
| DelegatePostValidStatus | string optional, advanced feature | This attribute permits configuration of a status code so that the content provider knows whether the SAML Browser/POST has been accepted. |
| DelegatePostResendStatus | string optional, advanced feature | If the status information returned by the content provider during a normal request matches the value configured for "DelegatePostResendStatus", the SAML Browser POST will be sent to the content provider again and the corresponding response will be sent to the client. |
| DelegatePostPolicy | enum: compat, sidecall, override, stateless-override optional, advanced default: compat | This attribute configures the behavior of delegation via HTTP-POST: compat: The first request is overridden by the delegation POST request and 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 POSTed with the delegation parameters. stateless-override: same as "override" but without tracking the state (delegation happens on each request). |
| DelegatePostTarget | string | Permits the configuration of a POST request to a specific location (for example, the URL of a SAML assertion consumer). The value of this attribute is a URL. This URL must meet the following conditions: It must start with a slash ("/"). Its prefix must be the original mapping path of the request. For example: The filter is mapped to /myapp/myfilter. In this case, possible values for the DelegatePostTarget attribute are: - "/myapp"- "/myapp/myfilter"- "/myapp/otherpath"Not allowed are: - "/otherapp"- "otherserver.otherdomain/otherpath" |
| DelegateCookie | newline-separated list of delegation specifications optional, advanced default: empty list | This attribute allows to delegate a cookie to a backend. The configuration syntax is the same as for the parameter "Delegate".This attribute should only be used when a CookieManager is configured (in the Http(s)Connector or in a CookieCacheFilter configured between the DelegationFilter and the backend). If no CookieManager is configured, the delegation of a cookie can be done via the "Delegate" attribute. In addition it is possible to add a condition of the form: Condition::<VARIABLE>:<expression>CIDR example: REMOTE_ADDR:CIDR/10.4.12.0/22/ |
| DelegateQuery | newline-separated list of delegation specifications optional, advanced feature default: empty list | Describes query parameters in the same syntax as above, but the values are passed as query arguments (“?n1=v1&n2=v2”) in the request line. |
| DelegateQueryPolicy | enum: INITIAL_ONLY, ALWAYS optional, advanced feature | This parameter configures the behaviours of delegation in the query. If "ALWAYS" is configured, the delegation will take place on every call. If "INITIAL_ONLY" is configured, the delegation is done only once (within the user session). |
| DelegateBasicAuth | newline-separated list of delegation specifications containing two entries optional, basic feature default: empty list | The Basic-Authentication HTTP header will be assembled from the two configured delegations, where the first one is the user ID and the second is the password. The entries are similar to those of the “Delegate” function, but the delegation name is fixed, so, the form is <source>:<key>. |
| DelegateSOAPSubstituedSecurityHeader | newline-separated list of delegation specification optional, advanced feature default: empty | In case the request is a SOAP/WSS request, the SOAP/WSS Security-header will be substituted with the value of the specified parameter "). |
| DelegateOutbound | newline-separated list of delegation specification optional, advanced default: empty | Allows to propagate HTTP headers to the client, e.g. to piggy-pack policy information, used by the client to adapt its access behaviour. Use this feature carefully (e.g. do not propagate security information like the secToken).In addition it is possible to add a condition of the form: Condition::<VARIABLE>:<expression>CIDR example: REMOTE_ADDR:CIDR/10.4.12.0/22/ |
| DelegateSource | delegation specification optional, advanced default: empty | Permits configuration of an IdentityCreationFilter whose state can be retrieved from the session. It is possible to configure several IdentityCreationFilters. Names are separated with ’ ’ or ’\n’. If a StateKey has been configured in the IdentityCreationFilter, the StateKey should be used instead of the IdentityCreationFilter name. |
| DelegateSource.Policy | enum: FIRST_FND, ALL, BY_TIMEdefault: FIRST_FND | How to handle the DelegateSource keys:FIRST_FND: just uses the StateKey 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 | boolean optional default: false | If set, the attributes of the children of the configured 'DelegateSource' are also handled. |
| Suppress | list of HTTP request header names optional, advanced securitydefault: empty | This attribute enables blocking the propagation of HTTP request headers.(cf. ‘Delegate’) |
| SuppressResponseHeader | list of HTTP response header names optional, advanced securitydefault: empty | This attribute enables blocking the propagation of HTTP response headers.(cf. ’DelegateOutbound’) |
| SOAPCharacterEncoding | enum: ’ASCII,US-ASCII,ISO_8859-1,ISO-8859-1,latin1,csISOLatin1,UTF-16BE,UTF-16LE,UTF-16,UTF-8’ | The character encoding used to externalize a parsed and modified SOAP message. |
| Encoding | enum: PLAIN,BASE64,URLENCODING, TRANSCODE_[encoding]default: ’PLAIN’ | Defines the default encoding for all delegations. When using the transcoding option, should be replaced with the desired output encoding. When nevisProxy is configured to run in ISO-8859-1 (using the variable user.locale within the bc.properties file) and defining this property to TRANSCODE_UTF-8, the delegated property will be converted from ISO-8859-1 to UTF-8 prior to delegation. |
| ParseSOAPRequest | boolean optional default: true | If true, SOAP messages will be parsed and internalized (DOM tree). Otherwise only string replacements are used to insert/append WSS header. |
| Kerberos.Policy | enum: NONE, PROACTIVE, CACHEoptional 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. |
| Kerberos.Delegation | string 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 | string optional default: /var/opt/<instance>/conf/nevisproxy-krb5.conf | Path to the config file for kerberos-negotiation. |
| DelegateToProxyLog | string optional | Describes the HTTP header of the request that will be traced as NProxyOp.The format of a list entry is:<source>:<parametername>:<tracename>where:<*source*> is one of "AUTH" or "CONST" or "ENV" or "PARAM" or "HEADER"Use this feature carefully (e.g., do not propagate security information like the SecToken). |
A sample configuration may look as follows:
<filter>
<filter-name>SecMsgDelegationFilter</filter-name>
<filter-class>ch::nevis::isiweb4::filter::delegation::DelegationFilter</filter-class>
<init-param>
<param-name>Delegate</param-name>
<param-value>
AUTH:user.auth.SecToken:isiwebsectoken
CONST:SomeValue:isiwebsomeattr
ENV:REMOTE_ADDR:REMOTE_ADDR
ENV:SSL_CIPHER:SSL_CIPHER
PARAM: someParameter: myheader
</param-value>
<description>HTTP header propagation to content providers</description>
</init-param>
</filter>