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.

StoreInterceptedRequest parameter - Limitations

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.

Classname

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

Library

libIdentityCreationFilters.so.1

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
• A newline-separated list to add extra cookie attributes to the cookie specified in the SendLoginCookie parameters. Each line has the following syntax:
  <name>[:<value>]

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 [bytes]

• Usage Constraints: optional, scaling

• Default: 5120

• This parameter defines the maximal body size of a SOAP-login request.

  The default is 5120. Usually, there is no need to change this 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.

InterceptionRedirect

• Type: enum

• Possible values: initial, always, never, true, false

• 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, security/clients
• Default: true
• Impact: Security feature, but exotic clients may have problems.
• With the parameter RenewIdentification, it is possible to configure client identifications for additional security after successful authentication.

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 [sec]

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

  Related configuration: LogoutURI in the HttpConnectorServlet

InactivePolicy

• Type: enum
• Possible values: none, min, max, global
• Usage Constraints: optional, advanced
• Default: none
• Impact: Complex configuration may lead to unintuitive behaviour.
• 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 [sec]

• 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 [sec]

• 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 do not work with HTTP/2. They are experimental when using TLSv1.3.

  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.

CheckAlwaysClientCert

• Type: boolean
• Usage Constraints: optional, basic feature
• Default: false
• If the client presents a certificate during the first login request, then there is a check to confirm that the same certificate is present during subsequent requests. This check can be disabled by setting the attribute to false.

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 a useful 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: false
• 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
• Impact: Trade-off between storing and forwarding the whole SOAP request vs. parsing it, storing the DOM-Tree and the header.
• 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.

PropagateFromEnv

• Type: string array
• Usage Constraints: optional, advanced
• Default: REMOTE_ADDR:connection.ClientIP SSL_PROTOCOL:connection.SSLProtocol SSL_CIPHER:connection.SSLCipher
• Impact: 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.

  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 (a corresponding DelegationFilter rule, therefore, is not required).

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

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. This parameter only works with the dynamic session management. If you use it with the legacy session management, the system throws an error NVCT-0015.

  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.

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.

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>