This repository has been archived on 2024-05-31. You can view files and clone it, but cannot push or open issues or pull requests.
authentik/website/docs/installation/configuration.mdx

413 lines
14 KiB
Plaintext

---
title: Configuration
---
This page details all the authentik configuration options that you can set via environment variables.
## About authentik configurations
:::info
The double-underscores are intentional, as all these settings are translated to YAML internally, and a double-underscore indicates the next level (a subsetting).
:::
All of these variables can be set to values, but you can also use a URI-like format to load values from other places:
- `env://<name>` Loads the value from the environment variable `<name>`. Fallback can be optionally set like `env://<name>?<default>`
- `file://<name>` Loads the value from the file `<name>`. Fallback can be optionally set like `file://<name>?<default>`
## Set your environment variables
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
<Tabs groupId="platform">
<TabItem value="docker-compose" label="Docker Compose" default>
If you are using Docker Compose, edit your <code>.env</code> file to append any keys that you want to add, and then run the following command to apply them:
```
docker-compose up -d
```
</TabItem>
<TabItem value="kubernetes" label="Kubernetes">
If you are running in Kubernetes, edit your <code>values.yaml</code> file to append any keys that you want to add, and then run the following commands to apply:
```
helm repo update
helm upgrade --install authentik authentik/authentik -f values.yaml
```
</TabItem>
</Tabs>
## Verify your configuration settings
To check if your config has been applied correctly, you can run the following command to output the full config:
<Tabs groupId="platform">
<TabItem value="docker-compose" label="Docker Compose" default>
```
docker-compose run --rm worker dump_config
```
</TabItem>
<TabItem value="kubernetes" label="Kubernetes">
```
kubectl exec -it deployment/authentik-worker -c authentik -- ak dump_config
```
</TabItem>
</Tabs>
## PostgreSQL Settings
- `AUTHENTIK_POSTGRESQL__HOST`: Hostname of your PostgreSQL Server
- `AUTHENTIK_POSTGRESQL__NAME`: Database name
- `AUTHENTIK_POSTGRESQL__USER`: Database user
- `AUTHENTIK_POSTGRESQL__PORT`: Database port, defaults to 5432
- `AUTHENTIK_POSTGRESQL__PASSWORD`: Database password, defaults to the environment variable `POSTGRES_PASSWORD`
- `AUTHENTIK_POSTGRESQL__USE_PGBOUNCER`: Adjust configuration to support connection to PgBouncer
- `AUTHENTIK_POSTGRESQL__USE_PGPOOL`: Adjust configuration to support connection to Pgpool
- `AUTHENTIK_POSTGRESQL__SSLMODE`: Strictness of ssl verification. Defaults to `verify-ca`
- `AUTHENTIK_POSTGRESQL__SSLROOTCERT`: CA root for server ssl verification
- `AUTHENTIK_POSTGRESQL__SSLCERT`: Path to x509 client certificate to authenticate to server
- `AUTHENTIK_POSTGRESQL__SSLKEY`: Path to private key of `SSLCERT` certificate
## Redis Settings
- `AUTHENTIK_REDIS__HOST`: Redis server host when not using configuration URL
- `AUTHENTIK_REDIS__PORT`: Redis server port when not using configuration URL
- `AUTHENTIK_REDIS__DB`: Redis server database when not using configuration URL
- `AUTHENTIK_REDIS__USERNAME`: Redis server username when not using configuration URL
- `AUTHENTIK_REDIS__PASSWORD`: Redis server password when not using configuration URL
- `AUTHENTIK_REDIS__TLS`: Redis server connection using TLS when not using configuration URL
- `AUTHENTIK_REDIS__TLS_REQS`: Redis server TLS connection requirements when not using configuration URL
## Result Backend Settings
- `AUTHENTIK_RESULT_BACKEND__URL`: Result backend configuration URL, uses [the Redis Settings](#redis-settings) by default
## Cache Settings
- `AUTHENTIK_CACHE__URL`: Cache configuration URL, uses [the Redis Settings](#redis-settings) by default
- `AUTHENTIK_CACHE__TIMEOUT`: Timeout for cached data until it expires in seconds, defaults to 300
- `AUTHENTIK_CACHE__TIMEOUT_FLOWS`: Timeout for cached flow plans until they expire in seconds, defaults to 300
- `AUTHENTIK_CACHE__TIMEOUT_POLICIES`: Timeout for cached policies until they expire in seconds, defaults to 300
- `AUTHENTIK_CACHE__TIMEOUT_REPUTATION`: Timeout for cached reputation until they expire in seconds, defaults to 300
:::info
`AUTHENTIK_CACHE__TIMEOUT_REPUTATION` only applies to the cache expiry, see [`AUTHENTIK_REPUTATION__EXPIRY`](#authentik_reputation__expiry) to control how long reputation is persisted for.
:::
## Channel Layer Settings (inter-instance communication)
- `AUTHENTIK_CHANNEL__URL`: Channel layers configuration URL, uses [the Redis Settings](#redis-settings) by default
## Broker Settings
- `AUTHENTIK_BROKER__URL`: Broker configuration URL, defaults to Redis using [the respective settings](#redis-settings)
- `AUTHENTIK_BROKER__TRANSPORT_OPTIONS`: Base64 encoded broker transport options
:::info
`AUTHENTIK_REDIS__CACHE_TIMEOUT_REPUTATION` only applies to the cache expiry, see [`AUTHENTIK_REPUTATION__EXPIRY`](#authentik_reputation__expiry) to control how long reputation is persisted for.
:::
## Listen Setting
- `AUTHENTIK_LISTEN__HTTP`: Listening address:port (e.g. `0.0.0.0:9000`) for HTTP (Applies to Server and Proxy outpost)
- `AUTHENTIK_LISTEN__HTTPS`: Listening address:port (e.g. `0.0.0.0:9443`) for HTTPS (Applies to Server and Proxy outpost)
- `AUTHENTIK_LISTEN__LDAP`: Listening address:port (e.g. `0.0.0.0:3389`) for LDAP (Applies to LDAP outpost)
- `AUTHENTIK_LISTEN__LDAPS`: Listening address:port (e.g. `0.0.0.0:6636`) for LDAPS (Applies to LDAP outpost)
- `AUTHENTIK_LISTEN__METRICS`: Listening address:port (e.g. `0.0.0.0:9300`) for Prometheus metrics (Applies to All)
- `AUTHENTIK_LISTEN__DEBUG`: Listening address:port (e.g. `0.0.0.0:9900`) for Go Debugging metrics (Applies to All)
- `AUTHENTIK_LISTEN__TRUSTED_PROXY_CIDRS`: List of CIDRs that proxy headers should be accepted from (Applies to Server)
Defaults to `127.0.0.0/8`, `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fe80::/10`, `::1/128`.
Requests directly coming from one an address within a CIDR specified here are able to set proxy headers, such as `X-Forwarded-For`. Requests coming from other addresses will not be able to set these headers.
## authentik Settings
### `AUTHENTIK_SECRET_KEY`
Secret key used for cookie signing and unique user IDs, don't change this after the first install.
### `AUTHENTIK_LOG_LEVEL`
Log level for the server and worker containers. Possible values: debug, info, warning, error
Starting with 2021.12.3, you can also set the log level to _trace_. This has no affect on the core authentik server, but shows additional messages for the embedded outpost.
:::danger
Setting the log level to `trace` will include sensitive details in logs, so it shouldn't be used in most cases.
Logs generated with `trace` should be treated with care as they can give others access to your instance, and can potentially include things like session cookies to authentik **and other pages**.
:::
Defaults to `info`.
### `AUTHENTIK_COOKIE_DOMAIN`
Which domain the session cookie should be set to. By default, the cookie is set to the domain authentik is accessed under.
### `AUTHENTIK_GEOIP`
Path to the GeoIP database. Defaults to `/geoip/GeoLite2-City.mmdb`. If the file is not found, authentik will skip GeoIP support.
### `AUTHENTIK_DISABLE_UPDATE_CHECK`
Disable the inbuilt update-checker. Defaults to `false`.
### `AUTHENTIK_ERROR_REPORTING`
- `AUTHENTIK_ERROR_REPORTING__ENABLED`
Enable error reporting. Defaults to `false`.
Error reports are sent to https://sentry.io, and are used for debugging and general feedback. Anonymous performance data is also sent.
- `AUTHENTIK_ERROR_REPORTING__SENTRY_DSN`
Sets the DSN for the Sentry API endpoint.
When error reporting is enabled, the default Sentry DSN will allow the authentik developers to receive error reports and anonymous performance data, which is used for general feedback about authentik, and in some cases, may be used for debugging purposes.
Users can create their own hosted Sentry account (or self-host Sentry) and opt to collect this data themselves.
- `AUTHENTIK_ERROR_REPORTING__ENVIRONMENT`
The environment tag associated with all data sent to Sentry. Defaults to `customer`.
When error reporting has been enabled to aid in debugging issues, this should be set to a unique
value, such as an e-mail address.
- `AUTHENTIK_ERROR_REPORTING__SEND_PII`
Whether or not to send personal data, like usernames. Defaults to `false`.
### `AUTHENTIK_EMAIL`
- `AUTHENTIK_EMAIL__HOST`
Default: `localhost`
- `AUTHENTIK_EMAIL__PORT`
Default: `25`
- `AUTHENTIK_EMAIL__USERNAME`
Default: `` (Don't add quotation marks)
- `AUTHENTIK_EMAIL__PASSWORD`
Default: `` (Don't add quotation marks)
- `AUTHENTIK_EMAIL__USE_TLS`
Default: `false`
- `AUTHENTIK_EMAIL__USE_SSL`
Default: `false`
- `AUTHENTIK_EMAIL__TIMEOUT`
Default: `10`
- `AUTHENTIK_EMAIL__FROM`
Default: `authentik@localhost`
Email address authentik will send from, should have a correct @domain
To change the sender's display name, use a format like `Name <account@domain>`.
### `AUTHENTIK_OUTPOSTS`
- `AUTHENTIK_OUTPOSTS__CONTAINER_IMAGE_BASE`
Placeholders:
- `%(type)s`: Outpost type; proxy, ldap, etc
- `%(version)s`: Current version; 2021.4.1
- `%(build_hash)s`: Build hash if you're running a beta version
Placeholder for outpost docker images. Default: `ghcr.io/goauthentik/%(type)s:%(version)s`.
- `AUTHENTIK_OUTPOSTS__DISCOVER`
Configure the automatic discovery of integrations. Defaults to `true`.
By default, the following is discovered:
- Kubernetes in-cluster config
- Kubeconfig
- Existence of a docker socket
### `AUTHENTIK_AVATARS`
Configure how authentik should show avatars for users. Following values can be set:
Default: `gravatar,initials`
- `none`: Disables per-user avatars and just shows a 1x1 pixel transparent picture
- `gravatar`: Uses gravatar with the user's email address
- `initials`: Generated avatars based on the user's name
- Any URL: If you want to use images hosted on another server, you can set any URL.
Additionally, these placeholders can be used:
- `%(username)s`: The user's username
- `%(mail_hash)s`: The email address, md5 hashed
- `%(upn)s`: The user's UPN, if set (otherwise an empty string)
Starting with authentik 2022.8, you can also use an attribute path like `attributes.something.avatar`, which can be used in combination with the file field to allow users to upload custom avatars for themselves.
Starting with authentik 2023.2, multiple modes can be set, and authentik will fallback to the next mode when no avatar could be found. For example, setting this to `gravatar,initials` will attempt to get an avatar from Gravatar, and if the user has not configured on there, it will fallback to a generated avatar.
### `AUTHENTIK_DEFAULT_USER_CHANGE_NAME`
:::info
Requires authentik 2021.12.5
:::
Enable the ability for users to change their name, defaults to `true`.
### `AUTHENTIK_DEFAULT_USER_CHANGE_EMAIL`
:::info
Requires authentik 2021.12.1
:::
Enable the ability for users to change their Email address, defaults to `false`.
### `AUTHENTIK_DEFAULT_USER_CHANGE_USERNAME`
:::info
Requires authentik 2021.12.1
:::
Enable the ability for users to change their Usernames, defaults to `false`.
### `AUTHENTIK_GDPR_COMPLIANCE`
:::info
Requires authentik 2021.12.1
:::
When enabled, all the events caused by a user will be deleted upon the user's deletion. Defaults to `true`.
### `AUTHENTIK_DEFAULT_TOKEN_LENGTH`
:::info
Requires authentik 2022.4.1
:::
Configure the length of generated tokens. Defaults to 60.
### `AUTHENTIK_IMPERSONATION`
:::info
Requires authentik 2022.4.2
:::
Globally enable/disable impersonation. Defaults to `true`.
### `AUTHENTIK_FOOTER_LINKS`
:::info
Requires authentik 2021.12.1
:::
This option configures the footer links on the flow executor pages.
The setting can be used as follows:
```
AUTHENTIK_FOOTER_LINKS='[{"name": "Link Name","href":"https://goauthentik.io"}]'
```
### `AUTHENTIK_LDAP__TASK_TIMEOUT_HOURS`
:::info
Requires authentik 2023.1
:::
Timeout in hours for LDAP synchronization tasks.
Defaults to `2`.
### `AUTHENTIK_LDAP__PAGE_SIZE`
:::info
Requires authentik 2023.6.1
:::
Page size for LDAP synchronization. Controls the number of objects created in a single task.
Defaults to `50`.
### `AUTHENTIK_LDAP__TLS__CIPHERS`
:::info
Requires authentik 2022.7
:::
Allows configuration of TLS Cliphers for LDAP connections used by LDAP sources. Setting applies to all sources.
Defaults to `null`.
### `AUTHENTIK_REPUTATION__EXPIRY`
:::info
Requires authentik 2023.8.2
:::
Configure how long reputation scores should be saved for in seconds. Note that this is different than [`AUTHENTIK_REDIS__CACHE_TIMEOUT_REPUTATION`](#redis-settings), as reputation is saved to the database every 5 minutes.
Defaults to `86400`.
### `AUTHENTIK_WEB__WORKERS`
:::info
Requires authentik 2022.9
:::
Configure how many gunicorn worker processes should be started (see https://docs.gunicorn.org/en/stable/design.html).
If running in Kubernetes, the default value is set to 2 and should in most cases not be changed, as scaling can be done with multiple pods running the web server.
Otherwise, authentik will use 1 worker for each 4 CPU cores + 1 as a value below 2 workers is not recommended.
### `AUTHENTIK_WEB__THREADS`
:::info
Requires authentik 2022.9
:::
Configure how many gunicorn threads a worker processes should have (see https://docs.gunicorn.org/en/stable/design.html).
Defaults to 4.
### `AUTHENTIK_WORKER__CONCURRENCY`
:::info
Requires authentik 2023.9.0
:::
Configure Celery worker concurrency for authentik worker (see https://docs.celeryq.dev/en/latest/userguide/configuration.html#worker-concurrency). This essentially defines the number of worker processes spawned for a single worker.
Defaults to 2.
## Custom python settings
To modify additional settings further than the options above allow, you can create a custom python file and mount it to `/data/user_settings.py`. This file will be loaded on startup by both the server and the worker. All default settings are [here](https://github.com/goauthentik/authentik/blob/main/authentik/root/settings.py)
:::caution
Using these custom settings is not supported and can prevent your authentik instance from starting. Use with caution.
:::