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


---

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

```
GET https://docs.fortifiedid.se/authn/readme.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.