IdentityCreationFilter

The task of the IdentityCreationFilter is to handle the authentication interception process of the user. This process consists of the following steps:

• Storing the intercepted request in case of multistep authentications.
• Driving the authentication process with the authentication service (e.g. nevisAuth) and the login page rendering service.
• Establishing the authenticated session.
• Forwarding the initial request.

If the IdentityCreationFilter receives the nevisAuth property (OutArg) nevis.transfer.destination=<URL> together with a response from nevisAuth, it generates a self-submitting form targeting the supplied destination.

Data may be added as hidden form fields by setting nevis.transfer.field.XX=YY, where XX is the name of the field and YY is its value.

Classname

ch::nevis::isiweb4::filter::auth::IdentityCreationFilter

Library

libIdentityCreationFilters.so.1

Default RequestFlags

+NEEDS_JSON_PARSING +NEEDS_PARAMS

Configuration

AuthenticationServlet

Type: string
Usage Constraints: required, basic connectivity

The name of the authentication servlet. An Esauth4ConnectorServlet or other authentication servlet must be configured.

LoginRendererServlet

Type: string
Usage Constraints: required, basic connectivity

The name of the servlet used for rendering login pages.

ResponseLogoutHeader

Type: string
Usage Constraints: optional

The authentication is removed, if the content provider sends the configured HTTP header in the response. See also ResponseLogoutHeaderMethod.

SendLoginCookie

Type: string
Usage Constraints: optional
Default: false

Cookie value is changed after logout, to distinguish timed out sessions from logged out sessions.

• After successful authentication, an additional Cookie is sent: Set-Cookie: IW4Login=login; Path=/; Version=1; HttpOnly
• After logout its value is changed: Set-Cookie: IW4Login=logout; Path=/; Version=1; HttpOnly

SendLoginCookie.CookieName

Type: string
Usage Constraints: optional

Configures the name of the cookie sent, when SendLoginCookie is configured to true.

SendLoginCookie.CookieDomain

Type: string
Usage Constraints: optional

Configures the domain of the cookie sent, when SendLoginCookie is configured to true.

SendLoginCookie.CookieHttpOnly

Type: boolean
Usage Constraints: optional
Default: true

Configures if the HttpOnly attribute should be set to the cookie sent, when SendLoginCookie is configured to true.

SendLoginCookie.CookieSecure

Type: boolean
Usage Constraints: optional
Default: true

Configures if the Secure attribute should be set to the cookie sent, when SendLoginCookie is configured to true.

SendLoginCookie.CookieMaxAge

Type: integer
Usage Constraints: optional
Default: 31536000

Sets the maximum age and the expiration directives of the login cookie in seconds. If you set this parameter to 0, the login cookie is sent without maximum age and expiration directives.

SendLoginCookie.ExtraAttributes

Type: newline-separated strings
Usage Constraints: optional
Syntax: <name>[:<value>]

A newline-separated list to add extra cookie attributes to the cookie specified in the SendLoginCookie parameters.

Realm

Type: string
Usage Constraints: required

If you have multiple ‘Domain’ sections in your authentication service configuration, this defines which one is used.

OriginalUrl.Enable

Type: boolean
Usage Constraints: required, basic, conditional
Default: false
Supported Pragmas: break

If this parameter is enabled, nevisProxy tracks the originally requested URL to your backend during the login process, and uses this URL for the final redirect to the application.

note

If enabled, this parameter solves many issues with multitabs, multi frames and wrong redirects after login. Therefore, we recommend enabling this feature.

OriginalUrl.SecretKey

Type: string
Usage Constraints: required if OriginalUrl.Enable is set to true, basic

Specifies the secret key used to encrypt the originally requested URL. Examples:

• ${exec: uuidgen}
• ${exec: cat /etc/machine-id}

OriginalUrl.ParameterName

Type: string
Usage Constraints: required, advanced
Default: requested_page

To avoid name clashes with other query parameters, it is possible to configure the parameter name for the requested URL. If the OriginalUrl.Enable parameter is enabled, nevisProxy stores the originally requested URL with this query parameter.

StateKey

Type: string
Usage Constraints: optional, very advanced

If the same value of the attribute StateKey is configured for two or more IdentityCreationFilters, they share the same ‘State’. (Advanced Option, only needed for special situations like an SSO domain with several entry URLs related to different authentication services)

BodyReadSize

Type: integer
Unit: bytes
Usage Constraints: optional, scaling
Default: 5120

This parameter defines the maximal body size of a SOAP-login request. Usually, there is no need to change the default value. However, the body size of some SOAP-logins is bigger than the configured default, which causes the error AUTH-0067 to occur. You can adapt (increase) the value of this parameter to anticipate such cases.

StoreInterceptedRequest

Type: boolean
Usage Constraints: optional, exotic clients
Default: true

After a successful authentication, the request is resent, usually using a redirect (see InterceptionRedirect). With StoreInterceptedRequest, the entire initial request is stored (instead of only remembering the request line), which allows POST requests to be intercepted transparently. If you do not need transparent logins on POST requests, you can switch this off to save memory.

note

Setting StoreInterceptedRequest to true and InterceptionRedirect to never at the same time may not work in some scenarios when OriginalUrl.Enable is false.

If OriginalUrl.Enable is true and InterceptionRedirectis never, then StoreInterceptedRequest will be set to true and StoreInterceptedRequest.MaxSize to 1.

See also Appendix G - Sizing Parameters in the Nevis Proxy.

StoreInterceptedRequest.MaxSize

Type: integer
Usage Constraints: optional, advanced

The maximum size (Content-Length) a request may have to be stored by StoreInterceptedRequest. If the 'Content-Length' is bigger than StoreInterceptedRequest.MaxSize, the StoreInterceptedRequest.FallbackURI is called.

StoreInterceptedRequest.FallbackURI

Type: string
Usage Constraints: optional, advanced

If the 'Content-Length' is bigger than StoreInterceptedRequest.MaxSize, the StoreInterceptedRequest.FallbackURI is called.

If used with InterceptionRedirect set to never it is recommended to set as well OriginalUrl.Enable to true otherwise some login-data may be sent to the backend.

InterceptionRedirect

Type: enum
Possible values: initial, always, never
Usage Constraints: optional, conditional
Default: initial

When the client sends the first request to a protected location (i.e. one with a mapped IdentityCreationFilter), the authentication flow is started, usually requiring user interaction on a login page.

• initial: With the default configuration of initial, the response to the initial request is a redirect with the appended query 'login'. The browser does not cache the login form. After successful authentication, a redirect to the initial request is sent (final redirect).
• always: If InterceptionRedirect is set to always, the login renderer is not invoked directly, but a redirect is sent and the login renderer is then invoked by that request.
• never: For clients which are not able to follow redirects. Therefore it is recommended for REST and SOAP clients, and for simple login flows where redirect is not necessary.

In case a direct response is received from nevisAuth and the interception redirect is enabled, the direct response will be ignored and the intercepted request will have precedence.

note

With InterceptionRedirect set to never a redirect may not be avoided if the request which triggered the login did contain a body.

If OriginalUrl.Enable is true the redirect URL we be either the StoreInterceptedRequest.FallbackURI (if it has been configured) or the URL of the incoming request which triggered the login. The redirect will only occur if the body is bigger then the configured StoreInterceptedRequest.MaxSize.

ClearFrames

Type: string array
Possible values: authenticate, stepup, unlock
Usage Constraints: optional, GUI
Default: empty

With the parameter ClearFrames, a colon-separated list of authentication methods can be configured. If one of the configured methods matches the actual one, any redirect is enforced through the submission of a JavaScript response. This JavaScript sets the login page into the top frame of the browser, to prevent problems with login-pages in small frames, and frame-in-frame problems of the application.

RenewIdentification

Type: boolean
Usage Constraints: optional
Default: true
Impact: Security feature, but exotic clients may have problems.

Configures the renewal of client identification (e.g. cookie) after successful authentication for additional security.

UserInputValidationRules

Type: List of form value rules
Usage Constraints: optional, advanced
Default: allow all

This parameter allows you to configure rules for the validation of the user input. The user input includes all request attributes from the query string or body. Any user input that does not match the corresponding rule is removed.

The code snippet below shows a part of a sample configuration:

 <param-value>
 isiwebuserid:^[0-9a-zA-Z]*$
 isiwebpasswd:^[0-9a-zA-Z]*$
 </param-value>

Rules are separated by new lines and are regular expressions using the syntax described in Regular expressions. The default regex type is "PCRE(da)".

InactiveInterval

Type: integer
Unit: seconds
Usage Constraints: optional, scaling
Default: 0

The MaxInactiveInterval on the dynamic session cache is a way to save resources by freeing idle sessions. If you have multiple SSO-domains and applications on the same nevisProxy with different inactivity settings, there is a conflict of interest between resource conservation and working comfort. To resolve this conflict, the value for the MaxInactiveInterval of the dynamic session cache is updated at every login or stepup.

The new value is derived from the filter’s configuration, a ‘global’ value returned from the authentication service and the current value according to the InactivePolicy.

A value of 0 means "not set", and maxInactive-Interval defined in the dynamic session cache or in the SessionManagementFilter is used as a fallback (See the chapter "Session handling").

note

There is no partial logout due to inactivity, nor will the value be reset if a user logs out from one SSO-domain or “steps-down” in authentication strength. If you need to set a timeout for security reasons, setting the ReauthInterval would be a better option.

InactivePolicy

Type: enum
Possible values: none, min, max, global
Usage Constraints: optional, advanced
Default: none

The parameter InactivePolicy configures how the InactiveInterval is set:

• min: InactiveInterval is used as the new value if it is less than the current value.
• max: InactiveInterval is used as the new value if it is greater than the current value.
• none: InactiveInterval is used if set. Otherwise, MaxInactiveInterval of the SessionManagementFilter is used.
• global: Same as none, but the value sent by the authentication service is taken. The value from InactiveInterval is used as a fallback.

ReauthInterval

Type: integer
Unit: seconds
Usage Constraints: optional, security/comfort
Default: 0 (not set)

Specifies a period of inactivity after a session gets into a locked state. If the session is accessed again, the user needs to unlock it with a credential. If you set this parameter to 0, the system does not use the parameter, but instead the attribute ch.nevis.session.reauthInterval returned by the authentication service. For more information, check the unlock authentication event in the nevisAuth reference guide.

SecTokenTolerance

Type: integer
Unit: seconds
Usage Constraints: optional, troubleshooting
Default: 120

With the parameter SecTokenTolerance, the tolerance for the Sectoken timeout check can be configured to account for the fact that machines for nevisAuth and nevisProxy may not have synchronized clocks. If for some reason the clock on the nevisAuth machine is faster, you may get a Sectoken at login that appears to have been signed in the future, therefore appearing not valid. The SecTokenTolerance configures the margin of error (number of seconds) between the clocks.

This parameter must be configured if the system time on the machine hosting the authentication service differs by more than 4 seconds from the one running nevisProxy. This is usually the case when NTP is not used or not working.

ClientCert

Type: string
Usage Constraints: optional, basic feature
Syntax: <SSLVerifyClient>:<SSLVerifyDepth>:<CertLocation>

This parameter enables X.509 client certificate authentication.

1. SSLVerifyClient: The possible values of this field are:

   • require: The client has to present a valid certificate.
   • optional: The client may (or may not) present a valid certificate.
   • optional_no_ca: The client may present a valid certificate, but it is not required to have a valid CA.
   • want: Get the client certificate without redirect. Basic verification of the client certificate like expiry or CA match is still done.

   The fields <SSLVerifyDepth> or <CertLocation> must not be set. All other verification is done by nevisAuth. The want option does not work with TLSv1.3

2. SSLVerifyDepth (optional): The system only accepts the certificate as belonging to the CA if the signature chain does not exceed this length.

   The signature chain contains all verified certificates from the CA to the certificate.

3. CertLocation (optional): This field is used to specify a redirection sublocation where an explicit client certificate retrieval is enforced. This parameter is only required for optional client certificate use. Sample configurations are:

   • require
   • require:5:subpath/
   • optional:3:/appl/getcert

   For optional and optional_no_ca, setting the absolute CertLocation is mandatory. On the corresponding CertLocation, an IdentityCreationFilter has to be mapped to be able to handle the redirect. For require, if configured, the CertLocation must be a relative sublocation.

info

If a dedicated optional certificate login location is used and the certificate should be requested everytime the client connects (not only when initiating the login session, as above), the following ClientCert init-param must be set instead: optional:2:/path/

Due to the upgrade to OpenSSL 1.1.1, problems with client certificates may occur. For more information and possible workarounds, see chapter Authentication with a client certificate and OpenSSL 1.1.1.

caution

Client certificates are experimental when using HTTP/2 or TLSv1.3.

HTTP/2 forbids TLS renegotiation once the server started reading the request, see RFC-9113. Therefore the following restrictions apply when using clients certificates with HTTP/2 in the IdentityCreationFilter:

• SSLVerifyClient must be set to optional, optional_no_ca or required in the Frontend connectors
• SSLOptions must include +ExportCertData in the Frontend connectors
• ClientCert should be set to want in the IdentityCreationFilter

caution

If the IdentityCreationFilter is not mapped directly to a path, but is used, for example, via a FilterMappingFilter, the generation process does not add the location configurations to the Apache configuration file. It is therefore recommended that you either use an ApacheConfigFilter to set these Apache directives, or add a dummy filter mapping for the given IdentityCreationFilter.

SendAlwaysClientCert

Type: boolean
Usage Constraints: optional, troubleshooting
Default: false

If this parameter is set to true, the client certificate is always sent to the authentication service. In all other cases, it is only sent if the initial request already contains a certificate. Receiving a client certificate in the middle of a login interception may be confusing to some authentication backends. Therefore, it is recommended using this parameter only when the end user is authenticated by a certificate.

NoClientCertRedirect

Type: string
Usage Constraints: optional, troubleshooting

If a URL is specified and no client certificate is found (when using ClientCert optional), a respective redirect is sent. This is useful to display the correct error page, if the login-page renderer does not provide this service.

StoreClientCert

Type: string
Usage Constraints: optional
Default: false

Stores the client certificate not only in the TLS context but also in the dynamic session store. This makes the certificate available for all subsequent HTTP requests within the client session if the client uses a connection that has not been authenticated by a 2-Way SSL/TLS authentication handshake. Used in conjunction with ClientCert.

SecureConnection

Type: boolean
Usage Constraints: optional, advanced
Default: true
Secure default: true

If set to true, the request must use a secure (TLS) connection. If not, access is denied.

OnlySoapHeader

Type: boolean
Usage Constraints: optional, advanced, security
Default: false

With OnlySoapHeader activated, intercepted SOAP requests are parsed and just the header part is sent to the authentication service. The internal representation of the XML structure is cached in the request. Trade-off between storing and forwarding the whole SOAP request vs. parsing it, storing the DOM-Tree and the header.

PropagateFromEnv

• Type: string array
• Usage Constraints: optional, advanced
• Default: REMOTE_ADDR:connection.ClientIP SSL_PROTOCOL:connection.SSLProtocol SSL_CIPHER:connection.SSLCipher

Low-level access to delegate things similar to ClientCert. An array of <key>:<name> pairs:

• <key>: the key used for the environment look-up
• <name>: the name used for the propagated property, if the value is present.

PropagateFromRequest

Type: string array
Usage Constraints: optional, advanced

Defines request attribute lookups.

RequestPeerCertificate

Type: string array
Usage Constraints: optional, advanced

With the optional attribute RequestPeerCertificate a : separated list of authenticate methods (authenticate, unlock, stepup) can be configured. For the methods in this list, the Client Certificate is requested. In order to work properly, a ClientCert has to be configured as well.

The attribute causes the reading of the client certificate in the listed authentication method's previous method. It doesn't force the client to send a certificate, just makes the proxy read it if it is provided.

caution

Client certificates do not work with HTTP/2. They are experimental when using TLSv1.3.

DelegateSecToken

Type: boolean
Usage Constraints: optional, basic feature
Default: false

If configured, the SecToken is added to the request HTTP headers with the name isiwebsectoken, and delegated towards the backend.

EntryPointID

Type: string
Usage Constraints: required

Entry ID sent to the authentication service to be added to the SecToken. This can be used by the content provider to distinguish e.g. between intranet- and external connections.

PropagateInterceptionState

Type: boolean
Usage Constraints: optional, advanced
Default: false

If true, the current state (login, setup, logout, authenticate, etc.) of the authentication is set as an HTTP response header with the name isiwebauthstate.

InvalidLogoutRedirect

Type: string
Usage Constraints: optional

Defines the redirect location for logouts requested with no prior valid authentication.

StoreProperties

Type: string
Usage Constraints: optional

Defines a colon or newline separated list of strings of the user-related authentication properties that should be stored into the session. It has the following format:

• the value none: no properties (except the security token) are stored
• a colon or newline separated list of property names: only those properties are stored
• a colon or newline separated list of property names all prefixed with a !: all properties except those defined here are stored
• not set or an empty list: all properties are stored.

Examples:

• Store everything except the properties prop1 and prop2: !prop1:!prop2
• Store only the properties prop1 and prop2: prop1:prop2

note

This does not count for the security token, the security token is always stored in the session.

TraceRemoteUser

Type: string
Usage Constraints: optional
Default: true

If set to true, the userID is set upon request via setRemoteUser. The userID is saved in the Apache ENV under the name REMOTE_USER.

SingleRequest

Type: boolean
Usage Constraints: optional
Default: false

If this attribute is set to true, only one request is passed through after a successful authentication. After the request has been passed through, the authentication is invalidated. To invalidate the entire session, you can use a LuaFilter. See: Invalidating the entire session after a single request for information on how to configure the LuaFilter.

The parameter SingleRequest does not work if you have simultaneously set the parameter ClientCert to want. In this case, use the LuaFilter solution (instead of the SingleRequest attribute).

CheckSecTokenRealm

Type: boolean
Usage Constraints: optional
Default: true

Assert that the sectoken realm matches the configured realm.

ResponseLogoutHeaderMethod

Type: enum
Possible values: kill, logout
Usage Constraints: optional
Default: kill

The attribute ResponseLogoutHeaderMethod configures the handling of logouts triggered by the content provider:

• kill: kill session on timeout and user-logout
• logout: logout session explicitly if user logs out

See also ResponseLogoutHeader.

RecheckAuthentication

Type: enum
Possible values: on, off, <integer>, auth:<parameter name>
Usage Constraints: optional
Default: off

If set to on, the filter attempts a stepup on the authentication service on every request. You can use this feature to ensure that the authentication service is consulted on changed authentication details for each incoming request. If an integer is set, a stepup is attempted every <integer> seconds. If set to auth:<parameter name>, the interval is consumed from nevisAuth parameter set on responses.

AllowLoginWithQueryString

Type: boolean
Usage Constraints: optional
Default: true
Secure default: false

If this attribute is set to false, the browser client must send its credentials with a POST or PUT request.

InitialURI

Type: string
Usage Constraints: optional
Default: not set

URI used after successful authentication, use this if you want a fixed entry URI. If both the InitialURI and StoreInterceptedRequest are set, the StoreInterceptedRequest has precedence over the InitialURI, and the latter is ignored.

caution

When InterceptionRedirect=never is set, after a successful login, the backend's content is accessed directly without evaluating the filters that are mapped for InitialURI.

OptimizeHttpAuth

Type: boolean
Usage Constraints: optional
Default: false

Optimize HTTP header based authentication (basic auth, kerberos) by ignoring the form parameters. This saves time for parsing the body, but may cause problems, if the same user is authenticated with kerberos and then wants to use a form-based authentication without closing the browser.

ExternalAction.reauth

Type: string
Usage Constraints: optional
Default: unlimited

Specifies if we allow a reauthentication triggered by an external action. The following values are allowed:

• invalidate: invalidate the session if we have an external reauth-request
• unlimited: do always a reauthentication
• <number>: do maximal <number> authentications, afterwards accept the session without reauthentication.

A reauthentication can be triggered via one of those ways:

• via the Validation.Rules parameter of the SessionManagementFilter by setting reauth as rule.
• via the LuaFilter by calling the request method reauthenticate.

PrivateUriSchemeRegex

Type: enum
Possible values: disabled, enabled
Usage Constraints: optional
Default: disabled

If enabled, all redirect URIs matching one of the regular expression patterns configured with the parameter PrivateUriSchemeRegex.Pattern are passed as is in the Location header sent back to the frontend. No base URI is added.

PrivateUriSchemeRegex.Pattern

Type: newline-separated string of regular expressions
Usage Constraints: optional
Default: [a-zA-Z0-9\.]+:/[a-zA-Z0-9]

This parameter is evaluated only if PrivateUriSchemeRegex is set to enabled. With this parameter, several regular expression patterns can be configured for private URIs. For more information, see the PrivateUriSchemeRegex parameter.

MaxLifetime

Type: integer
Usage Constraints: optional
Default: not set

Use this parameter to override the maximum lifetime of the authentication session. This allows you to change the timeout once the user is successfully logged in. Be aware that this timeout can be overwritten by the LuaFilter, via the session object method session:setMaxLifetime(timeout).

RenegotiateSSLOnLogout

Type: boolean
Usage Constraints: optional, security
Default: true
Secure default: true

If you set this parameter to true, the system renegotiates the SSL connection to the client after a logout.

RenegotiateCookieOnAuthContinue

Type: boolean
Usage Constraints: optional, security
Default: true
Secure default: true

If set to true, nevisProxy renegotiates the login cookie for each AUTH_CONTINUE response that comes from nevisAuth. It is recommended that you set this parameter to true for multi-step authentication flows to prevent session fixation attacks.

InvalidateSessionOnStateRemoval

Type: boolean
Usage Constraints: optional, advanced
Default: false

Set this parameter to true if the same StateKey is shared between several IdentityCreationFilter or SecurityRoleFilter and if you want to invalidate the whole session if any of the involved filter invalidates the given state (for example due to a timeout or a failure).

SynchronizeLoginRequests

Type: boolean
Usage Constraints: optional
Default: false

Set the parameter to true to prevent that during the login process several parallel requests do the login at the same time. The parameter works only if during login all requests got to the same instance.

SectokenExpireStrategy

Type: enum
Possible values: kill, logout
Usage Constraints: optional
Default: kill

The attribute SectokenExpireStrategy configures how to behave if a session with an expired sectoken has been accessed:

• kill: kill the session. The user may be redirected directly to the login page
• logout: logout from the session. The user will see the logout page, like on a manual logout.

Limitations of the StoreInterceptedRequest parameter

If you use the filter parameter StoreInterceptedRequest, take into account the following limitations:

1. If you set the filter parameter StoreInterceptedRequest to true and the filter parameter InterceptionRedirect to false or never at the same time, problems may arise in some scenarios. This might especially be the case if you have this setup in combination with logins from REST clients. In this situation, consider either changing the filter parameter StoreInterceptedRequest to false, or using the parameters OriginalUrl.Enable and OriginalUrl.SecretKey along with StoreInterceptedRequest set to true. If you need more information, refer to your Nevis contact person.

2. If both parameters StoreInterceptedRequest and OriginalUrl.Enable are set to true, nevisProxy removes all intercepted requests from the session after a successful login, except the one for which the login was made. This is done to avoid the following situation:

   • Assume a user has two tabs open in the browser.
   • The user makes the following requests just after a session has timed out:
   • Tab 1: Show account details page → Login is required.
   • Tab 2: Execute payment page → Login is required.
   • Tab 1: The user logs in. The Show account details page is returned.
   • The user drinks a coffee.
   • Tab 2 (Execute payment page) still shows the login screen. The user logs in → The payment is executed (although the user may not want this anymore).

To avoid this situation, nevisProxy removes the stored request of Tab 2 (the payment) from the session after the user has logged in on Tab 1.

3. If the parameter StoreInterceptedRequest is enabled, you have to adjust the following sizing parameters to accommodate your largest possible request:

   • ch.nevis.navajo.request.BufferSize in the file bc.properties
   • MySQLSessionStoreServlet.MaxAttributeSize in the file web.xml (if you persist sessions in a database)

In case you use upload requests of more than a couple of MBs, which might be intercepted, we recommend against configuring this parameter. If you really need the StoreInterceptedRequest parameter, either deal gracefully with failed uploads in your application, or ensure that your request is not intercepted before uploading. To this end, make sure you have an existing session with enough lifetime remaining before uploading. If you cannot follow these recommendations, you may have to configure the above mentioned sizing parameters to a very high value to accommodate your upload requests. Issues that arise from configuring these high values are not be supported and your overall performance might be impacted depending on your remote session store configuration and performance. As an alternative, you can change the StoreInterceptedRequest.MaxSize setting to a value smaller than the minimum of the above mentioned sizing parameters.

4. Chunked requests from the frontend are only stored if you set the parameter OriginalUrl.Enable to true. At the same time, the parameter StoreInterceptedRequest.MaxSize must be bigger than 0. Requests that are bigger than the configured StoreInterceptedRequest.MaxSize are not stored.

Examples

The sample code below shows a possible way of configuring the IdentityCreationFilter:

<filter>
 <filter-name>IdentityCreationFilter</filter-name>
 <filter-class>ch::nevis::isiweb4::filter::auth::IdentityCreationFilter</filter-class>
 <init-param>
          <param-name>AuthenticationServlet</param-name>
          <param-value>AuthConnector</param-value>
 </init-param>
 <init-param>
          <param-name>LoginRendererServlet</param-name>
          <param-value>LoginRenderer</param-value>
 </init-param>
 <init-param>
          <param-name>Realm</param-name>
          <param-value>test</param-value>
 </init-param>
 <init-param>
          <param-name>EntryPointID</param-name>
          <param-value>TheEntryPointId</param-value>
 </init-param>
</filter>

If the Dynamic Session Management Engine is in use, be sure to map the IdentityCreationFilter right after the SessionManagementFilter.

X509 client certificate authentication

nevisProxy (with apache as the carrier server) uses mod_ssl for client certificate authentication. The behavior of mod_ssl is not always optimal because client certificates may be requested far too often. This is the case when only trying to retrieve client certificates in an optional mode (a full TLS handshake is performed for each new connection). nevisProxy therefore supports an additional redirecting pattern that works as follows:

• If a new client identification is performed, the TLS certificate is requested from the client by redirecting to the specified sublocation.
• If the client does not send a certificate, the fact is stored in the dynamic session store. The client receives a redirect to the original location.

This behavior has also another effect: The client authentication using X509 certificates is performed during a normal GET request, which is preferable to authentication during POST requests. The reason is the POST body needs to be stored in the reverse proxy's memory (as it needs to be decrypted with the old context).

A common SOAP usage pattern (X509 client certificate authentication on a POST request), requires the client to support redirects when using optional client certificate authentication. If the client has sent a certificate during the login, the fingerprint of that certificate is stored in the session. In every subsequent request, there is a default check whether the client has sent a client certificate with the same fingerprint. That check can be disabled, see the parameter CheckAlwaysClientCert of the IdentityCreationFilter. The client may not present a certificate in the following two situations:

• The client does not resume the TLS session, (i.e., it is identified using cookies). That means a full TLS handshake is performed without requesting a client certificate.
• If the client is identified using the TLS session, an TLS renegotiation is started, if the remaining lifetime (as configured by maxLifeTime) of the TLS session (see the chapter TLS Cache Configuration) becomes less than the actual inactiveInterval of the container session (see the chapter HTTP session). In that case no client certificate is requested.

Due to the upgrade to OpenSSL 1.1.1, problems with client certificates may occur. For more information and possible workarounds, see chapter Authentication with a client certificate and OpenSSL 1.1.1. For this reason we recommend to set StoreClientCert to true.

Here is a sample configuration:

    <filter>
        <filter-name>OptionalSubLocationIdentityCreationFilter</filter-name>
        <filter-class>ch::nevis::isiweb4::filter::auth::IdentityCreationFilter</filter-class>
        <init-param>
            <param-name>AuthenticationServlet</param-name>
            <param-value>EsAuthConnector</param-value>
        </init-param>
        <init-param>
            <param-name>LoginRendererServlet</param-name>
            <param-value>LoginRenderer</param-value>
        </init-param>
        <init-param>
            <param-name>Realm</param-name>
            <param-value>test</param-value>
        </init-param>
        <init-param>
            <param-name>EntryPointID</param-name>
            <param-value>EntryPoint</param-value>
        </init-param>
        <init-param>
            <param-name>StoreInterceptedRequest</param-name>
            <param-value>false</param-value>
        </init-param>
        <init-param>
            <param-name>StoreClientCert</param-name>
            <param-value>true</param-value>
        </init-param>       
        <init-param>
            <param-name>ClientCert</param-name>
            <param-value>optional:2:/optional_cert/sublocation/sub/</param-value>
        </init-param>
    </filter>

caution

Client certificates do not work with HTTP/2. They are experimental when using TLSv1.3.

Invalidating the entire session after a single request

The parameter SingleRequest only invalidates the authentication, not the session. To invalidate the entire session, map the following LuaFilter between the IdentityCreationFilter and the backend:

<filter>
    <filter-name>InvalidateSessionAfterSingleRequest</filter-name>
    <filter-class>ch::nevis::isiweb4::filter::lua::LuaFilter</filter-class>

    <init-param>
        <param-name>Script.OutputHeaderFunctionName</param-name>
        <param-value>outputStream</param-value>
    </init-param>
    <init-param>
        <param-name>Script</param-name>
        <param-value>
            function outputStream(req, resp)
                session = req:getSession(false)
                if session ~= nil then
                    session:invalidate()
                end
            end
        </param-value>
    </init-param>
</filter>

Self-submitting form

The following self-submitting form is generated by nevisProxy when nevisAuth's response contains the property (OutArg) nevis.transfer.destination=<URL>:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
    <script nonce="<CSP-NONCE>" type="text/javascript">function sendForm() { document.forms[0].submit(); } document.addEventListener("DOMContentLoaded", sendForm); </script>
    <META name="robots" content="noindex" />
</head>
<body id="MyBody">
    <noscript><p><strong>Note:</strong> Since your browser does not support JavaScript, you must press the Continue button once to proceed.</p></noscript>
    <form action="<URL>" method="post" enctype="application/x-www-form-urlencoded">
        <div>
            <input type="hidden" name="<FIELD-1>" value="<VALUE-1>"/>
            <input type="hidden" name="<FIELD-2>" value="<VALUE-2>"/>
        </div>
        <noscript><div><input type="submit" value="Continue"/></div></noscript>
    </form>
</body>
</html>

The number of hidden form fields may vary depending on the use case.

The response sent to the client includes a Content-Security-Policy header with the generated nonce <CSP-NONCE>:

Content-Security-Policy: script-src 'nonce-<CSP-NONCE>';

In case several Content-Security-Policy headers are provided to the response by different sources, these headers can be combined into a single one with LuaFilters. See the example examples/WAF/Merge_script_src_from_Content_Security_Policy_headers.example in your nevisProxy installation folder.