AuthN

Introduction

The AuthN module deploys authenticators and exposes them through HTTP endpoints. Each authenticator performs a specific type of authentication.

AuthN is an HTTP module and supports the common HTTP module configuration.

Use an HTTP listener to provide the network endpoint.

Configuration

Note

Module name: AuthN

Properties

Name	Description	Default	Mandatory
http_context	HTTP context used by the AuthN module and its authenticators.	"/authn"
authenticators	List of authenticators to deploy.	[]
cache_control	Cache control policy configuration for static resources. See cache control.	See defaults
http_error	Default HTTP error configuration passed to authenticators that do not define their own error configuration.	{}

Example

{
    "name": "AuthN",
    "enabled": true,
    "config": {
        "http_context": "/authn",
        "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

Each object in the authenticators list defines one deployable authenticator. Authenticators are deployed independently and support the common HTTP configuration properties.

The order of entries in the list does not affect deployment.

Configuration properties common to all authenticators:

Properties

Name	Description	Default	Mandatory
id	Unique identifier within the current AuthN module.	""	true
type	Registered authenticator type.	""	true
enabled	Controls whether the authenticator is deployed.	true	false
config	Authenticator-specific configuration object.	{}	false
config.context_path	Absolute HTTP path to the authenticator. This path includes the shared http_context. **	""	false
config.base_path	Base path combined with the authenticator id when context_path is omitted.	""	false
config.webroot_dir	Directory from which authenticator resources are served. *	""	false
config.overlay_dir	Directory containing resources that override files in webroot_dir. *	""	false
config.cache_control	Cache-control policies for authenticator resources. See Cache control.	See default policies	false
config.success_location	Redirect target after successful authentication.	""	false
config.failure_location	Redirect target after failed authentication. Supports expression expansion.	""	false
config.cancel_location	Redirect target after cancelled authentication. Supports expression expansion.	""	false
config.expiry	How long the authentication result remains valid, expressed as an ISO-8601 duration.	"PT30M"	false
config.require_chain	Requires the authenticator to run as part of an authentication chain.	true	false
config.exports	Properties copied to the global authenticator state when authentication completes. See Exports.	[]	false
config.http_error	Authenticator-specific HTTP error configuration.	{}	false
config.logout_location	Redirect target after local logout for authenticators that use the default logout manager.	""	false
config.logout_suffix	Suffix appended to the authenticator route to form the logout route.	"/logout"	false
config.enable_throttling	When enabled, rejects concurrent requests for the same session with HTTP status 429.	false	false
config.header_whitelist_default	Replaces the built-in list of request headers exposed to the authenticator.	See defaults	false
config.header_whitelist	Adds request-header names to the effective whitelist. Matching is case-insensitive.	[]	false
config.logout_redir_pattern	Regular expression that defines the allowed logout redirect destinations.	Local redirects only	false
config.logout_redir_pattern_prefix	Prefix added to the logout redirect regular expression.	""	false
config.logout_redir_pattern_suffix	Suffix added to the logout redirect regular expression.	""	false

Example

{
    "id": "auth01",
    "type": "<auth-type>",
    "config": {
        "base_path": "/test/authn",
        "webroot_dir": "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"
                }
            ]
        }
    }
}

Note

The success_location, failure_location, and cancel_location redirect targets support authenticator expression expansion.

Example:

{
    "failure_location": "/authn/failure.html?trace_id=${session.trace_id}"
}

For example, this can pass the current trace ID to a custom error endpoint.

*) Part of the common HTTP configuration. Additional properties are described in the HTTP module configuration.

**) For an authenticator, context_path is the complete path and includes the module's http_context. In general HTTP module configuration, context_path is instead relative to http_context.

As an alternative, specify base_path. The module then combines it with the authenticator id to form context_path, so you do not need to specify context_path directly.

For the authenticator types covered by this documentation, context_path takes precedence if both properties are specified.

Request-header whitelist

Only whitelisted request headers are exposed through the authentication context. header_whitelist_default replaces the built-in list, while header_whitelist adds names to it.

The built-in whitelist contains:

• 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

Exports

Exports are configurable properties copied to the global authenticator state when authentication completes.

An exported value can be a static value or an expansion expression. The following scopes are available during expansion:

• session (the current session)
• state (authenticator-local state)

Session properties available during expansion:

Name	Description	Example
id	Session ID	${session.id}
trace_id	Current trace ID	${session.trace_id}
*	Named value stored in session	${session.name}

Properties

Name	Description	Default	Mandatory	Expanded
name	Name of the exported property.
value	Value of the exported property. String values support expression expansion.

Example

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

Error configuration

AuthN can serve a custom page when an HTTP error occurs. Configure the http_error object at module level to provide defaults for all authenticators, or on an individual authenticator to override those defaults. If no error page is configured, AuthN displays a standard page containing the HTTP status code and message.

Properties

Name	Description	Default	Mandatory
path_prefix	Common path prepended to each mappings.path value.
mappings	Mappings from HTTP status codes to error-page templates.
mappings.status	Exact status code or pattern used to select this mapping.
mappings.path	Path to an error-page template. Use either path or template.
mappings.template	Inline error-page template. Use either template or path.

Example

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

Status code expression

A status expression can be an exact integer code, such as 404, or a pattern such as "4**". Each asterisk (*) in a pattern represents one digit from 0 to 9. Use "*" to match any status code.

Error page templating

Error pages are rendered from templates on demand. A template can contain expansion expressions such as {{trace_id}} and {{status.code}}. The following values are available:

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><title>Error {{status.code}}</title></head>
    <body>
        <div>{{status.code}} {{status.message}}</div>
        <div>({{session_id}} / {{trace_id}})</div>
    </body>
</html>

Place resources referenced by the template, such as images or style sheets, in a published web root so that the browser can load them.

Cache control

Use the cache_control configuration property to add Cache-Control headers to static resources served by the AuthN module or an authenticator. Its policies list maps glob patterns to header values. Policies are evaluated in order, and the first matching pattern is applied.

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.

Properties

Name	Description	Default	Mandatory
policies	List of cache control policies. Evaluated in order; first match wins.
policies.pattern	Glob pattern matched against the request path.
policies.value	Cache-Control header value applied when the pattern matches.
policies.override	If true, overwrites an existing Cache-Control header. If false, only sets the header when none is present.	true

Default policies

The following policies are applied by default when cache_control is not configured:

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

Example

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

Logout redirect

To prevent malicious redirects after logout, AuthN validates every redirect destination against logout_redir_pattern. By default, only local destinations without a scheme, host, or port are allowed.

Use logout_redir_pattern_prefix and logout_redir_pattern_suffix to extend the default regular expression without replacing it.

The prefix, default pattern, and suffix must form a valid regular expression when combined.

Example:

{
    "logout_redir_pattern_prefix": "https://example\\.org/loggedout|"
}

This example allows https://example.org/loggedout in addition to the local destinations allowed by the default expression.

If a redirect destination does not match the expression, AuthN rejects it and logs the following error:

Invalid redirect location: <location>

In this section

• Sub modules