> For the complete documentation index, see [llms.txt](https://docs.fortifiedid.se/access/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fortifiedid.se/access/key-components/authenticators/common-configuration.md).

# Common configuration

Authenticator commons

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

## Authenticator

{% tabs %}
{% tab title="Properties" %}

<table data-full-width="true"><thead><tr><th>Name</th><th>Description</th><th>Default value</th><th data-type="checkbox">Mandatory</th></tr></thead><tbody><tr><td><code>id</code></td><td>Unique identifier of authenticator</td><td>N/A</td><td>true</td></tr><tr><td><code>type</code></td><td>Authenticator type (class name) or alias</td><td>N/A</td><td>true</td></tr><tr><td><code>config</code></td><td>Authenticator configuration object (optional)</td><td><code>{}</code></td><td>false</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

## Config

{% tabs %}
{% tab title="Properties" %}

<table data-full-width="true"><thead><tr><th>Name</th><th>Description</th><th>Default value</th><th data-type="checkbox">Mandatory</th></tr></thead><tbody><tr><td><code>context_path</code></td><td>The HTTP context path that the authenticator will be bound to. Use this property when configuring standalone authenticators. (<strong>mandatory unless <code>base_path</code> is specified</strong>)</td><td>N/A</td><td>true</td></tr><tr><td><code>base_path</code></td><td>Prefix of the context path that the authenticator will be bound to. This value is combined with the authenticator <code>id</code> to form a complete context path. Use this property when configuring chain and selectors. (<strong>mandatory unless <code>context_path</code> is specified</strong>)</td><td>N/A</td><td>true</td></tr><tr><td><code>success_location</code></td><td>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.</td><td>N/A</td><td>false</td></tr><tr><td><code>failure_location</code></td><td>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.</td><td>N/A</td><td>false</td></tr><tr><td><code>cancel_location</code></td><td>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.</td><td>N/A</td><td>false</td></tr><tr><td><code>webroot_dir</code></td><td>Path to directory serving as authenticator web root containing view resources.</td><td>N/A</td><td>false</td></tr><tr><td><code>overlay_dir</code></td><td>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.</td><td>${system.customer_home}/overlay</td><td>false</td></tr><tr><td><code>overlay_dirs</code></td><td>List of <code>overlay_dir</code>:s. Entries are processed in the defined order.</td><td>N/A</td><td>false</td></tr><tr><td><code>header_whitelist</code></td><td>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.</td><td><code>""</code></td><td>false</td></tr><tr><td><code>exports</code></td><td>List of properties exported when authenticator is complete. See below for details.</td><td><code>[]</code></td><td>false</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

{% hint style="info" %}
Redirect targets such as `success_location`, `failure_location`, and `cancel_location` support authenticator expression expansion.
{% endhint %}

Example:

```json
{
  "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.

{% hint style="info" %}
Integrity products assume that HTTPS is always used and therefore mark the session cookie as Secure and set SameSite=NONE.
{% endhint %}

```json
{
  "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).

{% tabs %}
{% tab title="Properties" %}

<table data-full-width="true"><thead><tr><th>Name</th><th>Description</th><th>Default</th><th data-type="checkbox">Expansion</th></tr></thead><tbody><tr><td>name</td><td>Name of property</td><td>N/A</td><td>false</td></tr><tr><td>value</td><td>Value of property. Can be a static value, and expansion expression or a combination of both.</td><td>N/A</td><td>true</td></tr></tbody></table>
{% endtab %}

{% tab title="Example" %}

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

{% endtab %}
{% endtabs %}

## 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:

<table data-full-width="true"><thead><tr><th>Name</th><th>Description</th><th data-type="checkbox">Case-insensitive</th></tr></thead><tbody><tr><td><code>request</code></td><td>The current HTTP request including <code>headers</code> and <code>params</code></td><td>false</td></tr><tr><td><code>session</code></td><td>The current session</td><td>false</td></tr><tr><td><code>state</code></td><td>The current authenticator state</td><td>false</td></tr><tr><td><code>exports</code></td><td>Exported authenticator state</td><td>false</td></tr><tr><td><code>input</code></td><td>authenticator input</td><td>false</td></tr><tr><td><code>subject</code></td><td>The current subject value, not an actual scope</td><td>false</td></tr><tr><td><code>util</code></td><td>Utilities</td><td>false</td></tr></tbody></table>

### Request

Generic HTTP request properties.

{% hint style="info" %}
Header names containing '`-`' must be addressed using bracket notation.

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

| Name             | Description                                                   | Syntax                                                                                            |
| ---------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `headers`        | Map/dictionary of request headers. Keys are case-insensitive. | <p><code>${request.headers.name}</code></p><p><code>${request.headers\['header-name']}</code></p> |
| `params`         | Map/dictionary of request parameters.                         | <p><code>${request.params.name}</code></p><p><code>${request.params\['param-name']}</code></p>    |
| `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.

{% hint style="info" %}
Authenticator properties can be made available to other authenticators using export.

Example:

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

{% endhint %}

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.fortifiedid.se/access/key-components/authenticators/common-configuration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.