Common configuration

All authenticators are configured in the same way and share some common configuration properties.

Authenticator

Properties

Name	Description	Default value	Mandatory
id	Unique identifier of authenticator	N/A	true
type	Authenticator type (class name) or alias	N/A	true
config	Authenticator configuration object (optional)	{}	false

Config

Properties

Name	Description	Default value	Mandatory
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	true
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	true
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	false
failure_location	The target location to where the user agent will be redirected when authentication fails. Supports expression expansion. If running in a chain, the first detected value on the way back to the first authenticator will be used. If not specified a built-in error page will be displayed.	N/A	false
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	false
webroot_dir	Path to directory serving as authenticator web root containing view resources. Defaults to a directory supplied by the authenticator type. Set it explicitly to replace the built-in user interface, see Custom frontend.	N/A	false
view_path	Entry point served for a view request, relative to the authenticator web root.	index.html	false
overlay_dir	Path to directory serving as authenticator overlay containing custom view resources. Resources in the overlay have precedence over resources in the web root, which means that if a resource exists in both, the one from the overlay will be served.	${system.customer_home}/overlay	false
overlay_dirs	List of overlay_dir:s. Entries are processed in the defined order.	N/A	false
enable_precompression	Serve precompressed .br or .gz variants of web root resources when the user agent accepts them.	false	false
enable_precompression_overlay	Serve precompressed variants of overlay resources when the user agent accepts them.	false	false
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. Header names are case insensitive.	""	false
exports	List of properties exported when authenticator is complete. See below for details.	[]	false

Note

Redirect targets such as success_location, failure_location, and cancel_location support authenticator expression expansion.

Example:

{
  "failure_location": "/authn/failure.html?trace_id=${session.trace_id}"
}

This is useful when redirecting to a custom error page such as InfoEndpoint and you want to include the current trace ID in the URL.

Advanced config

Advanced configuration properties are optional.

Name	Description	Default
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.	"true"
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.	"NONE"
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. Header names are case insensitive.	"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)

If authenticators are behind a proxy/firewall that manages/terminates SSL (i.e the connection between proxy/firewall and authenticators are not secure) the connection is secure from the browsers perspective.

Note

Integrity products assume that HTTPS is always used and therefore mark the session cookie as Secure and set SameSite=NONE.

{
  "name": "AuthN",
  "config": {
    "http_session_cookie_secure": true,
    "http_session_cookie_same_site": "NONE",
    "authenticators": []
}

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

Properties

Name	Description	Default	Expansion
name	Name of property	N/A	false
value	Value of property. Can be a static value, and expansion expression or a combination of both.	N/A	true

Example

"exports": [
    {
        "name": "method",
        "value": "uidpwdotp"
    },
    {
        "name": "uid",
        "value": "${state.username}"
    }
]

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:

Name	Description	Case-insensitive
request	The current HTTP request including headers and params	false
session	The current session	false
state	The current authenticator state	false
exports	Exported authenticator state	false
input	authenticator input	false
subject	The current subject value, not an actual scope	false
util	Utilities	false

Request

Generic HTTP request properties.

Note

Header names containing '-' must be addressed using bracket notation.

${request.headers['Content-Type']}

Name	Description	Syntax
headers	Map/dictionary of request headers. Keys 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.

Name	Description	Example
id	Session id	${session.id}
trace_id	Trace identifier	${session.trace_id}
*	Named value stored in session	${session.name}

State

Authenticator specific properties.

See authenticator specific documentation for available properties.

Note

Authenticator properties can be made available to other authenticators using export.

Example:

"exports": [
    {
      "name": "exported-name",
      "value": "${state.property-to-export}"
    }
]

Name	Description	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.

Name	Description	Example
*	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 a user action (like the id of a selected selector option).

See authenticator specific documentation for available input properties.

Name	Description	Example
*	Named authenticator input value.	${input.name}

Util

Name	Description	Example
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}