Common configuration
Authenticator commons
All authenticators are configured in the same way and share some common configuration properties.
Authenticator
id
Unique identifier of authenticator
N/A
type
Authenticator type (class name) or alias
N/A
config
Authenticator configuration object (optional)
{}
Config
context_path
The HTTP context path that the authenticator will be bound to. Use this property when configuring standalone authenticators. (mandatory unless base_path is specified)
N/A
base_path
Prefix of the context path that the authenticator will be bound to. This value is combined with the authenticator id to form a complete context path. Use this property when configuring chain and selectors. (mandatory unless context_path is specified)
N/A
success_location
Target location to where the user agent will be redirected when authentication has succeeded. Use this property when configuring standalone or top level chain authenticators.
N/A
failure_location
The target location to where the user agent will be redirected when authentication fails. If running in a chain, the first detected value on the way back to the first authenticator will be used. This enables the use of context specific locations. If not specified a built-in error page will be displayed.
N/A
cancel_location
Target location to where the user agent will be redirected when authentication is cancelled. If running in a chain, the first detected value on the way back to the first authenticator will be used. This enables the use of context specific locations. If not specified the authentication will be restarted and the first visible authenticator will be displayed.
N/A
webroot_dir
Path to directory serving as authenticator web root containing view resources.
N/A
overlay_dir
Path to directory serving as authenticator overlay containing custom view resources. Resources in overlay has precedence to resources in web root, which means that if a resource exists in both, the one from overlay will be served.
N/A
overlay_dirs
List of overlay_dir:s. Entries are processed in the defined order.
N/A
header_whitelist
List of HTTP headers to include in authentication context. This list is combined with the default list to form the complete header whitelist.
""
exports
List of properties exported exported when authenticator is complete. See below for details.
[]
Advanced config
Advanced configuration properties are optional.
expiry
Authentication expiry. A completed authentication is valid for this duration. Defaults to 30min.
PT30M
http_session_cookie_name
Name of session cookie to use for a specific authenticator
"__session"
http_session_timeout_ms
Custom HTTP session timeout in ms. When sharing context with other authenticators the value used is the value set by the first point of entry, session creation.
1800000
http_session_cookie_secure
Flag controlling if HTTP session cookie requires SSL ("Secure"). For more information, see below.
"false"
http_session_cookie_same_site
HTTP session cookie SameSite-policy controlling how third-party cookies are handled. Legal values are: "NONE" (requires SSL and Secure), "LAX" and "STRICT". For more information, see below.
"LAX"
http_request_body_limit
Max size of the request body allowed (Default: 2MB)
2097152
http_form_attr_limit
Max size of a form. (Default: 0,5MB)
524288
header_whitelist_default
Default list of HTTP headers to include in authentication context.
"Forwarded,X-Forwarded-For,X-Forwarded-Host,X-Forwarded-Proto,X-SSL-Client-Cert,X-SSL-Client-Chain,X-SSL-Client-Subject,X-SSL-Client-Verify,X-SSL-Protocol"
standalone
Flag forcing authenticator to operate in standalone mode or not. A standalone authenticator is not part of a chain. By default this value is calculated based on current configuration.
require_chain
Flag specifying if an authenticator must be executed inside a chain. Defaults to true for all non-chain authenticators.
true
HTTP session cookie control
When configuring authentication flows crossing site boundaries (for example by using SAML) advanced HTTP cookie configuration may be required since modern browsers doesn't allow sending cookies to other sites/domains and if an incoming ("returning") request doesn't contain a session cookie, the flow will fail.
For a cookie to be sent from one site to another the following is required:
The connection is secure (HTTPS)
Cookie is marked as "Secure" (only sent when connection is secure)
Cookie "SameSite" policy is set to "None" (cookies to other sites are allowed)
Using secure connections is always recommended. If authenticators are configured with SSL they will by default issue session cookies with the settings above.
If authenticators are behind a proxy/firewall that manages/terminates SSL (i.e the connection between proxy/firewall and authenticators are not secure) the cookie properties above must be configured manually:
Authenticator exports
When an authenticator is completed it will perform an export of configured properties. Exported properties are available for all following authenticators and pipes.
Property values supports authenticator expansion (see below).
name
Name of property
N/A
value
Value of property. Can be a static value, and expansion expression or a combination of both.
N/A
Authenticator expansion
Expansion is a configuration mechanism that replaces expressions ${scope.name} with values. Depending on where in the system lifecycle the expression is expanded, different scopes are available.
During authentication the following scopes exist:
The following scopes are available:
request
The current HTTP request including headers and params
session
The current session
state
The current authenticator state
exports
Exported authenticator state
input
authenticator input
subject
The current subject value, not an actual scope
util
Utilities
Request
Generic HTTP request properties.
Header names containing '-' must be addressed using bracket notation.
${request.headers['Content-Type']}
headers
Map/dictionary of request headers. Key are case-insensitive.
${request.headers.name}
${request.headers['header-name']}
params
Map/dictionary of request parameters.
${request.params.name}
${request.params['param-name']}
method
Request method (GET,PUT,POST, etc)
${request.method}
uri
Requested URI
${request.uri}
path
Requested path
${request.path}
remote_address
Client IP-address.
${request.remote_address}
Session
Properties stored in session.
id
Session id
${session.id}
*
Named value stored in session
${session.name}
State
Authenticator specific properties.
See authenticator specific documentation for available properties.
Authenticator properties can be made available to other authenticators using export.
Example:
*
Named value store in authenticator state.
${state.name}
Exports
Properties exported by authenticator (code or config) or pipe available to all following authenticator(s) and pipes.
See authenticator specific documentation for properties exported by default.
*
Named value exported by authenticator(s).
${exports.name}
Input
Authenticator input properties. Input is data provided by the authenticating user (like username or otp) or the result of an user action (like the id of a selected selector option).
See authenticator specific documentation for available input properties.
*
Named authenticator input value.
${input.name}
Util
uuid
Random UUID. A new UUID is generated for each expansion.
${util.uuid}
now
Timestamp in ISO 8601 format (2023-08-13T16:07:54+02:00)
${util.now}