Common configuration

Authenticator commons

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

Authenticator

Name Description Default value Mandatory

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

id

Unique identifier of authenticator

N/A

type

Authenticator type (class name) or alias

N/A

config

Authenticator configuration object (optional)

{}

Config

Name Description Default value Mandatory

Name	Description	Default value
`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.	`[]`

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

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`

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

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

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

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

"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

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

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

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}`

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

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

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

Name	Description	Example
`*`	Named value store in authenticator state.	`${state.name}`

*

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

Name	Description	Example
`*`	Named value exported by authenticator(s).	`${exports.name}`

*

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

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

*

Named authenticator input value.

${input.name}

Util

Name Description Example

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}`

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}

PreviousIntroduction NextWeb Authenticator API

Last updated 5 months ago

Authenticator

Config

Advanced config

HTTP session cookie control

Authenticator exports

Authenticator expansion

Request

Session

State

Exports

Input

Util