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:

Configuration | Modules

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

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

Configuration

Module name: AuthN

Properties

Name	Description	Default	Mandatory
context_path	Context path of module relative to module http_context. This context is used for serving common files used by all authenticators. ⚠️ Authenticators must not use this context, or parts of it, since it may cause session/cookie mixup and break authentication.	""
webroot_dir	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.	"resources"
overlay_dir	Web root overlay directory. (optional; if not configured overlay is disabled)
http_error	Default HTTP error configuration object. This object is passed on to each authenticator if not defined in authenticator config.
authenticators	List of authenticators to deploy

Example

{
    "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"
            }
        ]
    }
}

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:

Properties

Name	Description	Default	Mandatory
id	Unique identifier of authenticator. This can be any valid string value unique in the current configuration.
type	Authenticator type.
config	Authenticator specific configuration object. See authenticator specific documentation for details.	{}
config.context_path	Context path of authenticator. This is the absolute context of the authenticator to where a user agent should be redirected for authentication. **
config.base_path	Base of context path. If defined, this value will be combined with the authenticator id to form the context_path**
config.webroot_dir	Directory from where authenticator files are served. *
config.overlay_dir	Web root overlay. *
config.success_location	Location to where user agent is redirected after a successful authentication. This should be the address of the application requiring authentication.
config.failure_location	Location to where user agent is redirected after a failed authentication. This could be any resource accessible by the user agent.
config.exports	List of authenticator export properties.	[]
config.http_error	Authenticator specific HTTP error configuration object. Will inherit http_error object in module configuration if not defined.
config.logout_redir_pattern	Pattern matching allowed logout redirect locations. By default only local redirects (starting with "/" or "./") are supported.
config.logout_redir_pattern_prefix	Logout pattern prefix	""
config.logout_redir_pattern_suffix	Logout patters suffix	""

Example

{
    "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"
                }
            ]
        }
    }
}

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

Properties

Name	Description	Default	Mandatory	Expanded
name	Name of exported property
value	Value of exported property. If value is a string it will be expanded.

Example

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

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.

Properties

Name	Description	Default	Mandatory
path_prefix	Prefix for mapping paths to avoid duplication of paths in config.
mappings	List of status code to template mappings.
mappings.status	Status code expression. This expression is matched against the status code to find a template.
mappings.path	Path to error page template
mappings.template	Inline error page template

Example

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

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:

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

Example

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

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.

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>