Authelia
Get started

Server Authz Endpoints

Configuration

Example Configuration

This section is intended as an example configuration to help users with a rough contextual layout of this configuration section, it is not intended to explain the options. The configuration shown may not be a valid configuration, and you should see the options section below and the navigation links to properly understand each option individually.

configuration.yml
server:
  endpoints:
    authz:
      forward-auth:
        implementation: 'ForwardAuth'
        headers:
          Remote-User:
            user_attribute: 'username'
          Remote-Groups:
            user_attribute: 'groups'
          Remote-Name:
            user_attribute: 'display_name'
          Remote-Email:
            user_attribute: 'email'
        authn_strategies:
          - name: 'HeaderAuthorization'
            schemes:
              - 'Basic'
            scheme_basic_cache_lifespan: 0
          - name: 'CookieSession'
      ext-authz:
        implementation: 'ExtAuthz'
        headers:
          Remote-User:
            user_attribute: 'username'
          Remote-Groups:
            user_attribute: 'groups'
          Remote-Name:
            user_attribute: 'display_name'
          Remote-Email:
            user_attribute: 'email'
        authn_strategies:
          - name: 'HeaderAuthorization'
            schemes:
              - 'Basic'
            scheme_basic_cache_lifespan: 0
          - name: 'CookieSession'
      auth-request:
        implementation: 'AuthRequest'
        headers:
          Remote-User:
            user_attribute: 'username'
          Remote-Groups:
            user_attribute: 'groups'
          Remote-Name:
            user_attribute: 'display_name'
          Remote-Email:
            user_attribute: 'email'
        authn_strategies:
          - name: 'HeaderAuthorization'
            schemes:
              - 'Basic'
            scheme_basic_cache_lifespan: 0
          - name: 'CookieSession'
      legacy:
        implementation: 'Legacy'

name

string required

The first level under the authz directive is the name of the endpoint. In the example these names are forward-auth, ext-authz, auth-request, and legacy.

The name correlates with the path of the endpoint. All endpoints start with /api/authz/, and end with the name. In the example the forward-auth endpoint has a full path of /api/authz/forward-auth.

Valid characters for the name are alphanumeric as well as -, _, and /. They MUST start AND end with an alphanumeric character.

implementation

string required

The underlying implementation for the endpoint. Valid case-sensitive values are ForwardAuth, ExtAuthz, AuthRequest, and Legacy. Read more about the implementations in the reference guide.

headers

dictionary(object) not required

The headers value contains a dictionary where the dictionary key is the header name and the dictionary value is an object which determines the header value.

The header name must only contain valid header name characters, and must not be a standard or otherwise reserved header such as Content-Type, Location, Set-Cookie, WWW-Authenticate, or any of the Access-Control-*, X-Forwarded-*, and X-Original-* headers. As header names are case-insensitive the same header must not be configured more than once in differing cases.

Configuring this option replaces the default headers entirely, so the Remote-User, Remote-Groups, Remote-Name, and Remote-Email headers must be included if they are still required.

user_attribute

string required

The user attribute to derive the header value from. This attribute can be one available from the authentication backend or one determined via the User Attribute Definitions. Attribute names which are not known to Authelia, and attributes which are not mapped by the configured authentication backend, cause a startup error.

Attributes which resolve to a list are joined with a comma.

authn_strategies

list not required

A list of authentication strategies and their configuration options. These strategies are in order, and the first one which succeeds is used. Failures other than lacking the sufficient information in the request to perform the strategy immediately short-circuit the authentication, otherwise the next strategy in the list is attempted.

name

string required

The name of the strategy. Valid case-sensitive values are CookieSession, HeaderAuthorization, HeaderProxyAuthorization, HeaderAuthRequestProxyAuthorization, and HeaderLegacy. Read more about the strategies in the reference guide.

schemes

list(string) Basic not required

The list of schemes allowed on this endpoint. Options are Basic, and Bearer. This option is only applicable to the HeaderAuthorization, HeaderProxyAuthorization, and HeaderAuthRequestProxyAuthorization strategies and unavailable with the legacy endpoint which only uses Basic.

scheme_basic_cache_lifespan

string integer duration 0 seconds not required

Reference Note

This configuration option uses a common syntax. For more information please see both the configuration example and the Common Syntax: Duration reference guide.

The lifespan to cache username and password combinations when using the Basic scheme. This option enables the use of the caching which is completely disabled by default. This option must only be used when the Basic scheme is configured, and like all new options may not be used with the Legacy implementation.

Last updated on September 27, 2026
Edit this page on GitHub
Prev
Server Endpoint Rate Limits
Next
NTP