> For the complete documentation index, see [llms.txt](https://docs.fortifiedid.se/authn/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/authn/readme.md).

# AuthN

## Introduction

Module responsible for managing authenticators; web components performing authentication.

AuthN is a HTTP module. All configuration properties available on HTTP module are possible using on AuthN module. More details on HTTP modules is to found here:

{% embed url="<https://docs.fortifiedid.se/modules/configuration>" %}

Since the introduction of "listener" it is a good idea using that:

<https://docs.fortifiedid.se/common/server/http-listener>

## Configuration

{% hint style="info" %}
**Module name:** `AuthN`
{% endhint %}

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

<table><thead><tr><th>Name</th><th>Description</th><th>Default</th><th data-type="checkbox">Mandatory</th></tr></thead><tbody><tr><td><code>context_path</code></td><td><p>Context path of module relative to module <code>http_context</code>.</p><p>This context is used for serving common files used by all authenticators.</p><p><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> <em>Authenticators must not use this context, or parts of it, since it may cause session/cookie mixup and break authentication.</em></p></td><td><code>""</code></td><td>false</td></tr><tr><td><code>webroot_dir</code></td><td>Directory from where files are served. Note: this directory is for serving common files, all authenticators have their own web root for serving specific authenticator files.</td><td><code>"resources"</code></td><td>false</td></tr><tr><td><code>overlay_dir</code></td><td>Web root overlay directory. (optional; if not configured overlay is disabled)</td><td></td><td>false</td></tr><tr><td><code>cache_control</code></td><td>Cache control policy configuration for static resources. See <a href="#cache-control">cache control</a>.</td><td>See <a href="#cache-control">defaults</a></td><td>false</td></tr><tr><td><code>http_error</code></td><td>Default HTTP <a href="#error-configuration">error configuration</a> object. This object is passed on to each authenticator if not defined in authenticator config.</td><td></td><td>false</td></tr><tr><td><code>authenticators</code></td><td>List of <a href="#authenticator">authenticators</a> to deploy</td><td></td><td>false</td></tr></tbody></table>
{% endtab %}

{% tab title="Example" %}

```json
{
    "name": "AuthN",
    "enabled": true,
    "config": {
        "context_path": "/authn",  
        "webroot_dir": "web/authn",
        "overlay_dir": "/local/custom/authn",
        "authenticators" : [
            {
                "id": "auth01",
                "type": "<auth-type>",
                "config": {
                }
            },
            {
                "id": "auth02",
                "type": "<auth-type>",
                "config": {
                }
            }
        ]
    },
    "http_error": {
        "path_prefix": "web/error",
        "mappings": [
            {
                "status": "4**",
                "path": "4xx.html"
            },
            {
                "status": "*",
                "path": "error.html"
            }
        ]
    }
}
```

{% endtab %}
{% endtabs %}

### Authenticator

Object representing a deployable authenticator. Each authenticator is deployed in a separate (anonymous) module with support for HTTP, which means that authenticators support all common HTTP configuration properties.

Authenticators can be configured in any order.

Configuration properties common to all authenticators:

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

<table><thead><tr><th>Name</th><th>Description</th><th>Default</th><th data-type="checkbox">Mandatory</th></tr></thead><tbody><tr><td><code>id</code></td><td>Unique identifier of authenticator. This can be any valid string value unique in the current configuration.</td><td></td><td>true</td></tr><tr><td><code>type</code></td><td>Authenticator type.</td><td></td><td>true</td></tr><tr><td><code>config</code></td><td>Authenticator specific configuration object. See authenticator specific documentation for details.</td><td><code>{}</code></td><td>false</td></tr><tr><td><code>config.context_path</code></td><td>Context path of authenticator. This is the <em>absolute</em> context of the authenticator to where a user agent should be redirected for authentication. **</td><td></td><td>false</td></tr><tr><td><code>config.base_path</code></td><td>Base of context path. If defined, this value will be combined with the authenticator id to form the <code>context_path</code><em>**</em></td><td></td><td>false</td></tr><tr><td><code>config.webroot_dir</code></td><td>Directory from where authenticator files are served. *</td><td></td><td>false</td></tr><tr><td><code>config.overlay_dir</code></td><td>Web root overlay. *</td><td></td><td>false</td></tr><tr><td><code>config.cache_control</code></td><td>Cache control policy configuration for authenticator resources. Overrides module-level <code>cache_control</code> when set. See <a href="#cache-control">cache control</a>.</td><td>See <a href="#cache-control">defaults</a></td><td>false</td></tr><tr><td><code>config.success_location</code></td><td>Location to where user agent is redirected after a successful authentication. This should be the address of the application requiring authentication.</td><td></td><td>false</td></tr><tr><td><code>config.failure_location</code></td><td>Location to where user agent is redirected after a failed authentication. This could be any resource accessible by the user agent.</td><td></td><td>false</td></tr><tr><td><code>config.exports</code></td><td>List of authenticator <a href="#exports">export</a> properties.</td><td><code>[]</code></td><td>false</td></tr><tr><td><code>config.http_error</code></td><td>Authenticator specific HTTP <a href="#error-configuration">error configuration</a> object. Will inherit http_error object in module configuration if not defined.</td><td></td><td>false</td></tr><tr><td><code>config.logout_redir_pattern</code></td><td>Pattern matching allowed <a href="#logout-redirect">logout redirect</a> locations. By default only local redirects (starting with <code>"/"</code> or <code>"./"</code>) are supported.</td><td></td><td>false</td></tr><tr><td><code>config.logout_redir_pattern_prefix</code></td><td>Logout pattern prefix</td><td><code>""</code></td><td>false</td></tr><tr><td><code>config.logout_redir_pattern_suffix</code></td><td>Logout patters suffix</td><td><code>""</code></td><td>false</td></tr></tbody></table>
{% endtab %}

{% tab title="Example" %}

```json
{
    "id": "auth01",
    "type": "<auth-type>",
    "config": {
        "base_path": "/test/authn",
        "web_root": "resources/web",
        "overlay_dir": "/opt/local/web",
        "success_location": "/test/app",
        "failure_location": "/test/login_failed.html",
        "logout_redir_pattern": "https://example\.org/loggedout\.html",
        "http_error": {
            "mappings": [
                {
                    "status": 401,
                    "path": "web/error/custom.html"
                }
            ]
        }
    }
}
```

{% endtab %}
{% endtabs %}

\*) Part of common HTTP configuration, more properties are available in common module configuration.

\*\*) In an authentication context, `context_path` is the absolute path to the authenticator. This differs from general HTTP configuration, where it is relative to `http_context` (which is not used for authenticators).

To simplify configuration, you can instead specify `base_path`, which is automatically combined with the authenticator's ID to form `context_path`. If `base_path` is used, `context_path` does not need to be specified.

If both are specified, `context_path` will be used, except for chain and selector authenticators (see their respective documentation).

### Exports

Exports are configurable properties that will be added to the global authenticator state when the authenticator is completed.

The exported value can be either a static configured value or an expansion expression. During expansion the following scopes are available:

* `session` (the current session)
* `state` (authenticator local state)

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

<table><thead><tr><th>Name</th><th>Description</th><th>Default</th><th data-type="checkbox">Mandatory</th><th data-type="checkbox">Expanded</th></tr></thead><tbody><tr><td><code>name</code></td><td>Name of exported property</td><td></td><td>true</td><td>false</td></tr><tr><td><code>value</code></td><td>Value of exported property. If value is a string it will be expanded.</td><td></td><td>true</td><td>true</td></tr></tbody></table>
{% endtab %}

{% tab title="Example" %}

```json
"exports": [
    {
        "name": "export01",
        "value": "static export value"
    },
    {
        "name": "export02",
        "value": "${}"
    }
]
```

{% endtab %}
{% endtabs %}

### Error configuration

AuthN has support for serving custom error pages on failure. This is configured using the `http_error` object that can be present on module level (applies to all authenticators) or on individual authenticators. If not configured a standard error page displaying error code and message will be used.

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

<table><thead><tr><th>Name</th><th>Description</th><th>Default</th><th data-type="checkbox">Mandatory</th></tr></thead><tbody><tr><td><code>path_prefix</code></td><td>Prefix for mapping paths to avoid duplication of paths in config.</td><td></td><td>false</td></tr><tr><td><code>mappings</code></td><td>List of status code to template mappings.</td><td></td><td>false</td></tr><tr><td><code>mappings.status</code></td><td>Status code expression. This expression is matched against the status code to find a template.</td><td></td><td>true</td></tr><tr><td><code>mappings.path</code></td><td>Path to error page template</td><td></td><td>false</td></tr><tr><td><code>mappings.template</code></td><td>Inline error page template</td><td></td><td>false</td></tr></tbody></table>
{% endtab %}

{% tab title="Example" %}

```json
"http_error": {
    "path_prefix": "web/error",
    "mappings": [
        {
            "status": 404,
            "template": "<html><head>Error {{status.code}}</head><body>{{status.code}} {{status.message}} (id: {{trace_id}})</body></html>"
        },
        {
            "status": "4**",
            "path": "4xx.html"
        },
        {
            "status": "*",
            "path": "error.html"
        }
    ]
}
```

{% endtab %}
{% endtabs %}

#### Status code expression

Status expression can be either an exact code specified as an integer (`404`) or a simple pattern matching one or more codes (`"4**"`), where each asterisk (`*`) represents a single digit in the range `0-9`. A single `*` can be used to match all.

#### Error page templating

Error pages are templates rendered on demand. Templates may contain expansion expressions (`{{scope.name}}`).The following scopes/properties are available for expansion:

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

| Name             | Description                         |
| ---------------- | ----------------------------------- |
| `status.code`    | HTTP status code                    |
| `status.message` | HTTP status message (reason phrase) |
| `reason`         | Exception message (if available)    |
| `path`           | Current request path                |
| `session_id`     | Current session id                  |
| `trace_id`       | Current trace id                    |
| {% endtab %}     |                                     |

{% tab title="Example" %}

```html
<!-- Simple error template -->
<html>
    <head>Error {{status.code}}</head>
    <body>
        <div>{{status.code}} {{status.message}}</div>
        <div>({{session_id_id}} / {{trace_id}})</div>
    </body><
</html>
```

{% endtab %}
{% endtabs %}

If you include resources (like images) in your template, you must make sure they are available for user agent/browsers by placing them in a published web root.

### Cache control

Static resources served by the AuthN module and each authenticator can be given `Cache-Control` headers via the `cache_control` configuration property. It accepts a `policies` list where each policy maps a glob pattern to a `Cache-Control` header value. Policies are evaluated in order; the first matching pattern wins.

`cache_control` can be set at module level (applies to common resources) and at authenticator level (applies to authenticator-specific resources). Authenticator-level configuration overrides the module-level configuration when set.

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

<table><thead><tr><th>Name</th><th>Description</th><th>Default</th><th data-type="checkbox">Mandatory</th></tr></thead><tbody><tr><td><code>policies</code></td><td>List of cache control policies. Evaluated in order; first match wins.</td><td></td><td>true</td></tr><tr><td><code>policies.pattern</code></td><td>Glob pattern matched against the request path.</td><td></td><td>true</td></tr><tr><td><code>policies.value</code></td><td><code>Cache-Control</code> header value applied when the pattern matches.</td><td></td><td>true</td></tr><tr><td><code>policies.override</code></td><td>If <code>true</code>, overwrites an existing <code>Cache-Control</code> header. If <code>false</code>, only sets the header when none is present.</td><td><code>true</code></td><td>false</td></tr></tbody></table>
{% endtab %}

{% tab title="Default policies" %}
The following policies are applied by default when `cache_control` is not configured:

```json
{
    "cache_control": {
        "policies": [
            {
                "pattern": "**/assets/**",
                "value": "public, immutable, max-age=86400",
                "override": true
            },
            {
                "pattern": "**.{js,css,json,png,jpg,jpeg,gif,svg,webp,ico,woff,woff2,ttf,eot}",
                "value": "public, immutable, max-age=86400",
                "override": true
            },
            {
                "pattern": "**",
                "value": "no-store, no-transform, max-age=0",
                "override": true
            }
        ]
    }
}
```

{% endtab %}

{% tab title="Example" %}

```json
{
    "cache_control": {
        "policies": [
            {
                "pattern": "**/assets/**",
                "value": "public, immutable, max-age=86400"
            },
            {
                "pattern": "**.{js,css}",
                "value": "public, max-age=3600"
            },
            {
                "pattern": "**",
                "value": "no-store, no-transform, max-age=0"
            }
        ]
    }
}
```

{% endtab %}
{% endtabs %}

### Logout redirect

To prevent malicious redirects after logout all redirect locations are validated against a regular expression (regex) pattern (`logout_redir_pattern`). By default only local redirects (i.e. redirects without scheme, host and port) are allowed.

To simplify configuration the default pattern can be completed with a prefix (`logout_redir_pattern_prefix`) and a suffix (`logout_redir_pattern_suffix`).

Note that prefix/suffix must form a valid regex in combination with pattern.

Example:

```
// Add a single location
"logout_redir_pattern_prefix": "https://example\.org/loggedout|"
```

If an invalid redirect location is detected, the following error is raised/logged:

```
Invalid redirect location: <location>
```