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.propertiesMySQLSessionStoreServlet.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.
ch::nevis::isiweb4::filter::auth::IdentityCreationFilter
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
- After successful authentication, an additional Cookie is sent:
SendLoginCookie.CookieName
- Type: string
- Usage Constraints: optional
- Configures the name of the cookie sent, when
SendLoginCookie
is configured totrue
.
SendLoginCookie.CookieDomain
- Type: string
- Usage Constraints: optional
- Configures the domain of the cookie sent, when
SendLoginCookie
is configured totrue
.
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 totrue
.
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 totrue
.
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.
noteIf 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 totrue
, 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 errorAUTH-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
). WithStoreInterceptedRequest
, 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.noteSetting
StoreInterceptedRequest
totrue
andInterceptionRedirect
tonever
at the same time may not work in some scenarios whenOriginalUrl.Enable
isfalse
.If
OriginalUrl.Enable
istrue
andInterceptionRedirect
isnever
, thenStoreInterceptedRequest
will be set totrue
andStoreInterceptedRequest.MaxSize
to1
.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 thanStoreInterceptedRequest.MaxSize
, theStoreInterceptedRequest.FallbackURI
is called.
StoreInterceptedRequest.FallbackURI
- Type: string
- Usage Constraints: optional, advanced
- If the 'Content-Length' is bigger than
StoreInterceptedRequest.MaxSize
, theStoreInterceptedRequest.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 ofinitial
, 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
: IfInterceptionRedirect
is set toalways
, 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.
noteWith
InterceptionRedirect
set tonever
a redirect may not be avoided if the request which triggered the login did contain a body.If
OriginalUrl.Enable
istrue
the redirect URL we be either theStoreInterceptedRequest.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 configuredStoreInterceptedRequest.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 theMaxInactiveInterval
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 theSessionManagementFilter
is used as a fallback (See the chapter "Session handling").noteThere 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 theInactiveInterval
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 theSessionManagementFilter
is used.global
: Same asnone
, but the value sent by the authentication service is taken. The value fromInactiveInterval
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 attributech.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.
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. Thewant
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.infoIf 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.
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 tooptional
,optional_no_ca
orrequired
in the Frontend connectorsSSLOptions
must include+ExportCertData
in the Frontend connectorsClientCert
should be set towant
in the IdentityCreationFilterPropagateFromEnv
should containSSL_CLIENT_CERT:connection.ClientCert
in the IdentityCreationFilter
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, aClientCert
has to be configured as well.
With the optional attribute RequestPeerCertificate
a :
separated list of authentication methods (authenticate
, unlock
, stepup
) can be configured.
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.
In order to work properly, a ClientCert
has to be configured as well.
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 nameisiwebauthstate
.
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.
- the value
Examples:
- Store everything except the properties prop1 and prop2:
!prop1:!prop2
- Store only the properties prop1 and prop2:
prop1:prop2
noteThis does not count for the security token, the security token is always stored in the session.
- Store everything except the properties prop1 and prop2:
TraceRemoteUser
- Type: string
- Usage Constraints: optional
- Default:
true
- If set to
true
, the userID is set upon request viasetRemoteUser
. The userID is saved in the Apache ENV under the nameREMOTE_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 parameterClientCert
towant
. In this case, use the LuaFilter solution (instead of theSingleRequest
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-logoutlogout
: 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 toauth:<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
andStoreInterceptedRequest
are set, theStoreInterceptedRequest
has precedence over theInitialURI
, and the latter is ignored.cautionWhen
InterceptionRedirect=never
is set, after a successful login, the backend's content is accessed directly without evaluating the filters that are mapped forInitialURI
.
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-requestunlimited
: 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 theSessionManagementFilter
by settingreauth
as rule. - via the
LuaFilter
by calling the request methodreauthenticate
.
- via the
Specifies if we allow a reauthentication triggered by an external action. This parameter can be used together with an action on the client identification. The client identification defines the external action on which the IdentityCreationFilter can react.
The following values are allowed:
invalidate
: invalidate the session if we have an external reauth-requestunlimited
: 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 theSessionManagementFilter
by settingreauth
as rule. - via the
LuaFilter
by calling the request methodreauthenticate
.
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 toenabled
. With this parameter, several regular expression patterns can be configured for private URIs. For more information, see thePrivateUriSchemeRegex
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
.
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 eachAUTH_CONTINUE
response that comes from nevisAuth. It is recommended that you set this parameter totrue
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 sameStateKey
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: 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 pagelogout
: logout from the session. The user will see the logout page, like on a manual logout.
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 actualinactiveInterval
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>
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.