287 lines
8.0 KiB
Markdown
287 lines
8.0 KiB
Markdown
---
|
|
title: "Files"
|
|
description: "Using the YAML File Configuration Method."
|
|
lead: "Authelia can be configured via files. This section describes utilizing this method."
|
|
date: 2022-06-15T17:51:47+10:00
|
|
draft: false
|
|
images: []
|
|
menu:
|
|
configuration:
|
|
parent: "methods"
|
|
weight: 101200
|
|
toc: true
|
|
---
|
|
|
|
## Formats
|
|
|
|
The only supported configuration file format is [YAML](#yaml).
|
|
|
|
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 behaviour with the
|
|
following syntax:
|
|
|
|
```bash
|
|
authelia --config config.custom.yml
|
|
```
|
|
|
|
#### YAML Validation
|
|
|
|
We recommend utilizing [VSCodium](https://vscodium.com/) or [VSCode](https://code.visualstudio.com/), both with the
|
|
[YAML Extension](https://open-vsx.org/extension/redhat/vscode-yaml) by RedHat to validate this file type.
|
|
|
|
## 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:
|
|
|
|
```bash
|
|
authelia --config configuration.yml --config config-acl.yml --config config-other.yml
|
|
authelia --config configuration.yml,config-acl.yml,config-other.yml
|
|
```
|
|
|
|
Authelia's configuration files use the YAML format. A template with all possible options can be found at the root of the
|
|
repository [here](https://github.com/authelia/authelia/blob/master/config.template.yml).
|
|
|
|
*__Important Note:__ You should not have configuration sections such as Access Control Rules or OpenID Connect clients
|
|
configured in multiple files. If you wish to split these into their own files that is fine, but if you have two files that
|
|
specify these sections and expect them to merge properly you are asking for trouble.*
|
|
|
|
### 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:
|
|
|
|
```bash
|
|
docker run -d --volume /path/to/config:/config authelia:authelia:latest authelia --config=/config/configuration.yaml --config=/config/configuration.acl.yaml
|
|
```
|
|
|
|
See the [Docker Documentation](https://docs.docker.com/engine/reference/commandline/run/) 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:
|
|
|
|
```yaml
|
|
version: "3.8"
|
|
services:
|
|
authelia:
|
|
container_name: authelia
|
|
image: authelia/authelia:latest
|
|
command:
|
|
- "authelia"
|
|
- "--config=/config/configuration.yaml"
|
|
- "--config=/config/configuration.acl.yaml"
|
|
|
|
```
|
|
|
|
See the [compose file reference](https://docs.docker.com/compose/compose-file/compose-file-v3/#command) for more
|
|
information.
|
|
|
|
### Kubernetes
|
|
|
|
An excerpt from a Kubernetes container that allows you to specify multiple configuration files is as follows:
|
|
|
|
```yaml
|
|
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:fix-missing-head-handler
|
|
command:
|
|
- authelia
|
|
args:
|
|
- '--config=/configuration.yaml'
|
|
- '--config=/configuration.acl.yaml'
|
|
```
|
|
|
|
See the Kubernetes [workloads documentation](https://kubernetes.io/docs/concepts/workloads/pods/#pod-templates) or the
|
|
[Container API docs](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.23/#container-v1-core) for more
|
|
information.
|
|
|
|
## File Filters
|
|
|
|
Experimental file filters exist which allow modification of all configuration files after reading them from the
|
|
filesystem but before parsing their content. These filters are _**NOT**_ covered by our
|
|
[Standard Versioning Policy](../../policies/versioning.md). There __*WILL*__ be a point where the name of the CLI
|
|
argument or environment variable will change and usage of these will either break or just not work.
|
|
|
|
The filters are configured as a list of filter names by the `--config.experimental.filters` CLI argument and
|
|
`X_AUTHELIA_CONFIG_EXPERIMENTAL_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.
|
|
|
|
Examples:
|
|
|
|
```bash
|
|
authelia --config config.yml --config.experimental.filters expand-env,template
|
|
```
|
|
|
|
```text
|
|
X_AUTHELIA_CONFIG_EXPERIMENTAL_FILTERS=expand-env,template
|
|
```
|
|
|
|
### Expand Environment Variable Filter
|
|
|
|
The name used to enable this filter is `expand-env`.
|
|
|
|
This filter is the most common filter type used by many other applications. It is similar to using `envsubst` where it
|
|
replaces a string like `$EXAMPLE` or `${EXAMPLE}` with the value of the `EXAMPLE` environment variable.
|
|
|
|
### Go Template Filter
|
|
|
|
The name used to enable this filter is `template`.
|
|
|
|
This filter uses the [Go template engine](https://pkg.go.dev/text/template) to render the configuration files. It uses
|
|
similar syntax to Jinja2 templates with different function names.
|
|
|
|
#### Functions
|
|
|
|
In addition to the standard builtin functions we support several other functions.
|
|
|
|
##### iterate
|
|
|
|
The `iterate` function generates a list of numbers from 0 to the input provided. Useful for ranging over a list of
|
|
numbers.
|
|
|
|
Example:
|
|
|
|
```yaml
|
|
numbers:
|
|
{{- range $i := iterate 5 }}
|
|
- {{ $i }}
|
|
{{- end }}
|
|
```
|
|
|
|
##### env
|
|
|
|
The `env` function returns the value of an environment variable or a blank string.
|
|
|
|
Example:
|
|
|
|
```yaml
|
|
default_redirection_url: 'https://{{ env "DOMAIN" }}'
|
|
```
|
|
|
|
##### split
|
|
|
|
The `split` function splits a string by the separator.
|
|
|
|
Example:
|
|
|
|
```yaml
|
|
access_control:
|
|
rules:
|
|
- domain: 'app.{{ env "DOMAIN" }}'
|
|
policy: bypass
|
|
methods:
|
|
{{ range _, $method := split "GET,POST" "," }}
|
|
- {{ $method }}
|
|
{{ end }}
|
|
```
|
|
|
|
##### join
|
|
|
|
The `join` function is similar to [split](#split) but does the complete oppiste, joining an array of strings with a
|
|
separator.
|
|
|
|
Example:
|
|
|
|
```yaml
|
|
access_control:
|
|
rules:
|
|
- domain: ['app.{{ join (split (env "DOMAINS") ",") "', 'app." }}']
|
|
policy: bypass
|
|
```
|
|
|
|
##### contains
|
|
|
|
The `contains` function is a test function which checks if one string contains another string.
|
|
|
|
Example:
|
|
|
|
```yaml
|
|
{{ if contains (env "DOMAIN") "https://" }}
|
|
default_redirection_url: '{{ env "DOMAIN" }}'
|
|
{{ else }}
|
|
default_redirection_url: 'https://{{ env "DOMAIN" }}'
|
|
{{ end }}
|
|
```
|
|
|
|
##### hasPrefix
|
|
|
|
The `hasPrefix` function is a test function which checks if one string is prefixed with another string.
|
|
|
|
Example:
|
|
|
|
```yaml
|
|
{{ if hasPrefix (env "DOMAIN") "https://" }}
|
|
default_redirection_url: '{{ env "DOMAIN" }}'
|
|
{{ else }}
|
|
default_redirection_url: 'https://{{ env "DOMAIN" }}'
|
|
{{ end }}
|
|
```
|
|
|
|
##### hasSuffix
|
|
|
|
The `hasSuffix` function is a test function which checks if one string is suffixed with another string.
|
|
|
|
Example:
|
|
|
|
```yaml
|
|
{{ if hasSuffix (env "DOMAIN") "/" }}
|
|
default_redirection_url: 'https://{{ env "DOMAIN" }}'
|
|
{{ else }}
|
|
default_redirection_url: 'https://{{ env "DOMAIN" }}/'
|
|
{{ end }}
|
|
```
|
|
|
|
##### lower
|
|
|
|
The `lower` function is a conversion function which converts a string to all lowercase.
|
|
|
|
Example:
|
|
|
|
```yaml
|
|
default_redirection_url: 'https://{{ env "DOMAIN" | lower }}'
|
|
```
|
|
|
|
##### upper
|
|
|
|
The `upper` function is a conversion function which converts a string to all uppercase.
|
|
|
|
Example:
|
|
|
|
```yaml
|
|
default_redirection_url: 'https://{{ env "DOMAIN" | upper }}'
|
|
```
|