Common configuration

Authenticator commons

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
type	Authenticator type (class name) or alias	N/A
config	Authenticator configuration object (optional)	{}

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

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.	"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:

{
  "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
value	Value of property. Can be a static value, and expansion expression or a combination of both.	N/A

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
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']}

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

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

"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 an 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}