Files

Loading behavior and Discovery#

There are several options which affect the loading of files:

Configuration Paths#

Configuration options can be discovered via either the Argument or Environment Variable, but not both at the same time. If both are specified the Argument takes precedence and the Environment Variable is ignored. It is generally recommended that if you’re using a container that you use the Environment Variable as this will allow you to execute other commands from the context of the container more easily.

Formats#

The supported configuration file formats are YAML, TOML, and JSON. The format of each file is determined by its extension:

Files with any other extension are parsed as YAML for backwards compatibility when they are explicitly specified, and are skipped entirely when they are discovered within a directory.

Formats can be freely mixed. Multiple configuration files of differing formats are merged exactly the same way as multiple files of the same format, see Multiple Configuration Files.

It’s important that you sufficiently validate your configuration file. While we produce console errors for users in many misconfiguration scenarios it’s not perfect. Each file type has recommended methods for validation.

YAML#

Authelia loads configuration.yml as the configuration if you just run it. You can override this behavior with the following syntax:

docker run authelia/authelia:latest authelia --config config.custom.yml

authelia --config config.custom.yml

YAML Validation#

We recommend utilizing VSCodium or VSCode, both with the YAML Extension by RedHat to validate this file type.

This extension allows validation of the format and schema of a YAML file. To facilitate schema validation we publish a set of JSON schemas which you can include as a special comment in order to validate the YAML file further. See the JSON Schema reference guide for more information including instructions on how to utilize the schemas.

TOML#

Authelia loads a configuration file with the .toml extension using the TOML parser. For example:

docker run authelia/authelia:latest authelia --config configuration.toml

authelia --config configuration.toml

JSON#

Authelia loads a configuration file with the .json extension using the JSON parser. For example:

docker run authelia/authelia:latest authelia --config configuration.json

authelia --config configuration.json

JSON Validation#

The JSON schemas we publish can be referenced directly from a JSON configuration file via the $schema property, which most editors will use to validate the file as you edit it.

Multiple Configuration Files#

You can have multiple configuration files which will be merged in the order specified. If duplicate keys are specified the last one to be specified is the one that takes precedence. Example:

docker run -d authelia/authelia:latest authelia --config configuration.yml --config config-acl.yml --config config-other.yml

docker run -d authelia/authelia:latest authelia --config configuration.yml,config-acl.yml,config-other.yml

authelia --config configuration.yml --config config-acl.yml --config config-other.yml

authelia --config configuration.yml,config-acl.yml,config-other.yml

A template with all possible options can be found at the root of the repository here.

Container#

By default, the container looks for a configuration file at /config/configuration.yml.

Docker#

This is an example of how to override the configuration files loaded in docker:

docker run -d --volume /path/to/config:/config authelia:authelia:latest authelia --config=/config/configuration.yml --config=/config/configuration.acl.yml

See the Docker Documentation for more information on the docker run command.

Docker Compose#

An excerpt from a docker compose that allows you to specify multiple configuration files is as follows:

services:
  authelia:
    container_name: 'authelia'
    image: 'authelia/authelia:latest'
    command:
      - 'authelia'
      - '--config=/config/configuration.yml'
      - '--config=/config/configuration.acl.yml'

See the compose file reference for more information.

Kubernetes#

An excerpt from a Kubernetes container that allows you to specify multiple configuration files is as follows:

kind: Deployment
apiVersion: apps/v1
metadata:
  name: authelia
  namespace: authelia
  labels:
    app.kubernetes.io/instance: authelia
    app.kubernetes.io/name: authelia
spec:
  replicas: 1
  selector:
    matchLabels:
      app.kubernetes.io/instance: authelia
      app.kubernetes.io/name: authelia
  template:
    metadata:
      labels:
        app.kubernetes.io/instance: authelia
        app.kubernetes.io/name: authelia
    spec:
      enableServiceLinks: false
      containers:
        - name: authelia
          image: docker.io/authelia/authelia:latest
          command:
            - authelia
          args:
            - '--config=/configuration.yml'
            - '--config=/configuration.acl.yml'

See the Kubernetes workloads documentation or the Container API docs for more information.

File Filters#

File filters exist which allow modification of all configuration files after reading them from the filesystem but before parsing their content. Unless explicitly specified these filters are NOT covered by our Standard Versioning Policy.

The filters are configured as a list of filter names by the --config.filters CLI argument and X_AUTHELIA_CONFIG_FILTERS environment variable. We recommend using the environment variable as it ensures commands executed from the container use the same filters. If both the CLI argument and environment variable are used the environment variable is completely ignored.

Filters can either be used on their own, in combination, or not at all. The filters are processed in order as they are defined. You can preview the output of the YAML files when processed via the filters using the authelia config template command.

Examples#

docker run -d authelia/authelia:latest authelia --config /config/configuration.yml --config.filters template

authelia --config /config/configuration.yml --config.filters template

docker run -d -e X_AUTHELIA_CONFIG_FILTERS=template -e X_AUTHELIA_CONFIG=/config/configuration.yml authelia/authelia:latest authelia

X_AUTHELIA_CONFIG_FILTERS=template X_AUTHELIA_CONFIG=/config/configuration.yml authelia

Values#

The values option allows injecting values into the configuration from an external source. If the filter supports it then the filter itself will detail the accessibility of the values and other data available.

The values files must have one of the .yml, .yaml, .json, or .toml extensions which determines the format used to parse them. When multiple values files are specified they are loaded in the order specified and each one is deep-merged on top of the values loaded so far, i.e. where a key exists in both and both values are mappings they are recursively merged, otherwise the value from the later file replaces the value from the earlier file.

The values files are only loaded when one of the configured filters utilizes them, which is currently only the Go Template Filter. If none of the configured filters utilize the values then the values files are ignored and a warning is logged.

Mapping keys are always strings regardless of the file format. The YAML format permits keys which are not strings, for example 1 or true, and these keys are converted to their string representation at every level which means a key of 1 must be accessed as the string 1. Numeric keys are converted from their parsed value so a key of 1.0 is also accessed as the string 1, and a null key such as ~ is accessed as the string null. It is an error for two keys in the same mapping to convert to the same string, for example 1 and '1'.

Filters#

The following are the available filters.

Go Template Filter#

The name used to enable this filter is template. This filter is considered stable.

This filter uses the Go template engine to render the configuration files. It uses similar syntax to Jinja2 templates with different function names.

Comprehensive examples are beyond what we support and people wishing to use this should consult the official Go template engine documentation for syntax instructions. We also log the generated output at each filter stage as a base64 string when trace logging is enabled.

Values#

The template filter allows access to both the values file data, and some various metadata. See the table below for more information.

Multiple values files can be specified, see Values for information on how they’re merged.

Referencing a key which does not exist, for example {{ .Values.Missing }}, is an error rather than rendering an empty or placeholder value. To optionally reference a key use the index function, for example {{ index .Values "Missing" | default "fallback" }}.

Delimiters#

You can adjust the delimiters of this filter using the options below. Please note that an empty string is the same as the default values of {{ and }}.

Functions#

In addition to the standard built-in functions we support several other functions. These functions should operate similarly to Helm template functions.

See the Templating Reference Guide for more information.

Expand Environment Variable Filter#

The expand-env filter has been officially removed as of v4.40.0.