Common

Syntax#

The following represent common syntax used within the configuration which have specific format requirements that are used in multiple areas. This is intended on assisting in understanding these specific values, and not as a specific guide on configuring any particular instance.

Dictionary Reference#

The dictionary reference syntax is a syntax where often the key can arbitrarily be set by an administrator and the key can be used elsewhere to reference this configuration.

For instance, when considering the below example if the key named policies was noted as a dictionary within the documentation then the aribtrary_name could be used elsewhere to communicate the policy to be applied, like in the usage_example section where it’s used as the policy.

policies:
  arbitrary_name:
    enable: true

usage_example:
  - name: 'example'
    policy: 'arbitrary_name'

Duration#

The base type for this syntax is a string, and it also handles integers however this is discouraged.

If you supply an integer, it is considered a representation of seconds. If you supply a string, it parses the string in blocks of quantities and units (number followed by a unit letter). For example 5h indicates a quantity of 5 units of h.

The following is ignored or stripped from the input:

• all spaces
• leading zeros
• the word and

While you can use multiple of these blocks in combination, we suggest keeping it simple and use a single value. In addition it’s important to note that the format while somewhat human readable still requires you closely follow the expected formats.

Unit Legend#

The following is a legend for the unit formats available in this syntax. The long form units are only available from v4.38.0 or newer.

Examples#

Address#

The base type for this syntax is a string.

The address type is a string that indicates how to configure a listener (i.e. listening for connections) or connector (i.e. opening remote connections), which are the two primary categories of addresses.

Query Parameters#

Some schemes support parameters, this table describes them.

Format#

This section outlines the format for these strings. The formats use a conventional POSIX format to indicate optional and required elements. The square brackets [] surround optional portions, and the angled brackets <> surround required portions. Required portions may exist within optional portions, in which case they are often accompanied with other format specific text which indicates if the accompanying text exists then it is actually required, otherwise it’s entirely optional.

The square brackets indicate optional sections, and the angled brackets indicate required sections. The following sections elaborate on this. Sections may only be optional for the purposes of parsing, there may be a configuration requirement that one of these is provided.

Hostname#

The following format represents the hostname format. It’s valid for both a listener and connector in most instances. Refer to the individual documentation for an option for clarity. In this format as per the notation the scheme and port are optional. The default for these when not provided varies.

[<scheme>://]<hostname>[:<port>][/<path>]

Port#

The following format represents the port format. It’s valid only for a listener in most instances. Refer to the individual documentation for an option for clarity. In this format as per the notation the scheme and hostname are optional. The default for the scheme when not provided varies, and the default for the hostname is all available addresses when not provided.

[<scheme>://][hostname]:<port>[/<path>]

File Descriptors#

The following format represents the file descriptor format. It’s valid only for a listener. Refer to the individual documentation for an option for clarity. In this format as per the notation there are no optional portions.

The File Descriptor format also accepts a query string. The Query Parameters described above control certain behavior of this address type.

fd://<file descriptor number>

fd://<file descriptor number>?umask=0022

fd://<file descriptor number>?path=auth

fd://<file descriptor number>?umask=0022&path=auth

Unix Domain Socket#

The following format represents the unix domain socket format. It’s valid for both a listener and connector in most instances. Refer to the individual documentation for an option for clarity. In this format as per the notation there are no optional portions.

The Unix Domain Socket format also accepts a query string. The Query Parameters described above control certain behavior of this address type.

unix://<path>

unix://<path>?umask=0022

unix://<path>?path=auth

unix://<path>?umask=0022&path=auth

Examples#

Various examples for these formats.

0.0.0.0
tcp://0.0.0.0
tcp://0.0.0.0/subpath
tcp://0.0.0.0:9091
tcp://0.0.0.0:9091/subpath
tcp://:9091
tcp://:9091/subpath
0.0.0.0:9091

udp://0.0.0.0:123
udp://:123

unix:///var/lib/authelia.sock

scheme#

The entire scheme is optional, but if the scheme host delimiter :// is in the string, the scheme must be present. The scheme must be one of the following (the listeners and connectors columns indicate support for the scheme on the respective address type):

If the scheme is absent, the default scheme is assumed. If the address has a / prefix it’s assumed to be unix, otherwise it’s assumed to betcp. If the scheme is unix it must be suffixed with an absolute path i.e. /var/local/authelia.sock would be represented as unix:///var/run/authelia.sock.

hostname#

The hostname is required if the scheme is one of the tcp or udp schemes and there is no port specified. It can be any IP that is locally addressable or a hostname which resolves to a locally addressable IP.

If specifying an IPv6 it should be wrapped in square brackets. For example for the IPv6 address ::1 with the tcp scheme and port 80 the correct address would be tcp://[::1]:80.

port#

The hostname is required if the scheme is one of the tcp or udp schemes and there is no hostname specified.

Regular Expressions#

We have several sections of configuration that utilize regular expressions. We use the Google RE2 regular expression engine which is the full Go regular expression syntax engine, the syntax of which is described here by the authors. It’s very similar to regular expression engines like PCRE, Perl, and Python; with the major exceptions being that it doesn’t have backtracking.

It’s recommended to validate your regular expressions manually either via tools like Regex 101 (ensure you pick the Golang option) or some other means.

It’s important when attempting to utilize a backslash that it’s utilized correctly. The YAML parser is likely to parse this as you trying to use YAML escape syntax instead of regex escape syntax. To avoid this use single quotes instead of no quotes or double quotes.

Good Example:

domain_regex: '^(admin|secure)\.example\.com$'

Bad Example:

domain_regex: "^(admin|secure)\.example\.com$"

Network#

We support a network syntax which unmarshalls strings into a network range. The string format uses the standard CIDR notation and assumes a single host (adapted as /32 for IPv4 and /128 for IPv6) if the CIDR suffix is absent.

Structures#

The following represent common data structures used within the configuration which have specific requirements that are used in multiple areas. This is intended on assisting in understanding these specific structures, and not as a specific guide on configuring any particular instance.

TLS#

Various sections of the configuration use a uniform configuration section called tls which configure TLS socket and TLS verification parameters. This section documents the common parts of this structure. By default Authelia uses the system certificate trust for TLS certificate verification but you can augment this with the global certificates_directory option, and can disable TLS certificate verification entirely with the skip_verify option.

tls:
  server_name: 'example.com'
  skip_verify: false
  minimum_version: 'TLS1.2'
  maximum_version: 'TLS1.3'
  certificate_chain: |
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----
  private_key: |
    -----BEGIN PRIVATE KEY-----
    ...
    -----END PRIVATE KEY-----

server_name#

The key server_name overrides the name checked against the certificate in the verification process. Useful if you require an IP address for the host of the backend service but want to verify a specific certificate server name.

skip_verify#

The key skip_verify completely negates validating the certificate of the backend service. This is not recommended, instead you should tweak the server_name option, and the global option certificates directory.

minimum_version#

Controls the minimum TLS version Authelia will use when performing TLS handshakes. The possible values are TLS1.3, TLS1.2, TLS1.1, TLS1.0, SSL3.0. Anything other than TLS1.3 or TLS1.2 are very old and deprecated. You should avoid using these and upgrade your backend service instead of decreasing this value. At the time of this writing SSL3.0 will always produce errors.

maximum_version#

Controls the maximum TLS version Authelia will use when performing TLS handshakes. The possible values are TLS1.3, TLS1.2, TLS1.1, TLS1.0, SSL3.0. Anything other than TLS1.3 or TLS1.2 are very old and deprecated. You should avoid using these and upgrade your backend service instead of decreasing this value. At the time of this writing SSL3.0 will always produce errors.

certificate_chain#

The certificate chain/bundle to be used with the private_key to perform mutual TLS authentication with the server.

The value must be one or more certificates encoded in the DER base64 (RFC4648) encoded PEM format. If more than one certificate is provided, in top down order, each certificate must be signed by the next certificate if provided.

private_key#

The private key to be used with the certificate_chain for mutual TLS authentication. The public key material of the private key must match the private key of the first certificate in the certificate_chain.

The value must be one private key encoded in the DER base64 (RFC4648) encoded PEM format and must be encoded per the PKCS#8, PKCS#1, or SECG1 specifications.

Server Buffers#

Various sections of the configuration use a uniform configuration section called buffers which configure HTTP server buffers. Notably the server and metrics telemetry sections. This section documents the common parts of this structure.

buffers:
  read: 4096
  write: 4096

read#

Configures the maximum request size. The default of 4096 is generally sufficient for most use cases.

write#

Configures the maximum response size. The default of 4096 is generally sufficient for most use cases.

Server Timeouts#

Various sections of the configuration use a uniform configuration section called timeouts which configure HTTP server timeouts. Notably the server and metrics telemetry sections. This section documents the common parts of this structure.

timeouts:
  read: '6s'
  write: '6s'
  idle: '30s'

read#

Configures the server read timeout.

write#

Configures the server write timeout.

idle#

Configures the server idle timeout.

Historical References#

This contains links to historical anchors.

Duration Notation Format#

See duration common syntax.