Skip to main content

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​

If you are using Docker Compose, edit your .env file to append any keys that you want to add, and then run the following command to apply them:

docker compose up -d

Verify your configuration settings​

To check if your config has been applied correctly, you can run the following command to output the full config:

docker compose run --rm worker ak dump_config

PostgreSQL Settings​

authentik requires PostgreSQL for application data, configuration, sessions, and background task coordination.

Use this section to configure:

  • the primary PostgreSQL connection
  • TLS settings for PostgreSQL
  • connection behavior and pooler compatibility
  • optional read replicas

For operational runbooks, see the PostgreSQL upgrade guides for Docker Compose and Kubernetes. For backup guidance, see Backup and restore.

Connection settings​

These settings define the primary database connection used for writes and, unless read replicas are configured, for reads.

  • AUTHENTIK_POSTGRESQL__HOST

    Hostname or IP address of the PostgreSQL server.

  • AUTHENTIK_POSTGRESQL__PORT

    Port on which PostgreSQL is listening.

    Default: 5432

  • AUTHENTIK_POSTGRESQL__USER

    PostgreSQL username used by authentik.

  • AUTHENTIK_POSTGRESQL__PASSWORD

    PostgreSQL password used by authentik.

    If unset, authentik falls back to POSTGRES_PASSWORD. This fallback exists for the default Docker Compose setup and should not be relied on in more complex deployments.

  • AUTHENTIK_POSTGRESQL__NAME

    Name of the PostgreSQL database to use.

Hot-reloading

The AUTHENTIK_POSTGRESQL__HOST, AUTHENTIK_POSTGRESQL__PORT, AUTHENTIK_POSTGRESQL__USER, and AUTHENTIK_POSTGRESQL__PASSWORD settings support hot-reloading and can be changed without restarting authentik. However, adding or removing read replicas requires a restart.

SSL/TLS settings​

Use these settings when your PostgreSQL server requires TLS or mutual TLS.

  • AUTHENTIK_POSTGRESQL__SSLMODE

    Controls how TLS is used and verified for PostgreSQL connections.

    Default: verify-ca

    • disable: No SSL is used.
    • allow: Use SSL if available, but don't perform verification.
    • prefer: Attempt an SSL connection first, fall back to non-SSL if it fails.
    • require: Require an SSL connection, but without certificate verification.
    • verify-ca: Require SSL and verify that the server certificate is signed by a trusted CA.
    • verify-full: Require SSL, verify the CA, and verify that the server hostname matches the certificate.

  • AUTHENTIK_POSTGRESQL__SSLROOTCERT

    Path to the CA certificate file used to verify the PostgreSQL server certificate.

    Required for verify-ca and verify-full.

  • AUTHENTIK_POSTGRESQL__SSLCERT

    Path to the client certificate file.

    Required only if PostgreSQL is configured for mutual TLS and requires client certificates.

  • AUTHENTIK_POSTGRESQL__SSLKEY

    Path to the private key corresponding to AUTHENTIK_POSTGRESQL__SSLCERT.

For more detail, see Django's PostgreSQL documentation and the PostgreSQL libpq SSL documentation.

Connection management​

These settings control connection reuse and compatibility with connection poolers such as PgBouncer or Pgpool.

  • AUTHENTIK_POSTGRESQL__CONN_MAX_AGE

    Maximum age of a database connection in seconds.

    • 0 (default): Connections are closed after each request.
    • greater than 0: Enables persistent connections, with the value defining the maximum lifetime.
    • None: Keep connections open indefinitely.

    Indefinite connection reuse is often a poor fit for poolers in session mode. See Django's documentation on persistent connections.

  • AUTHENTIK_POSTGRESQL__CONN_HEALTH_CHECKS

    Enables health checks before reusing persistent connections.

    Default: false

    This helps avoid errors caused by stale connections that were closed by PostgreSQL, a proxy, or a connection pooler. See Django's documentation.

  • AUTHENTIK_POSTGRESQL__DISABLE_SERVER_SIDE_CURSORS

    Disables server-side cursors.

    Default: false

    Set this to true when using transaction-based pooling, or when you encounter cursor-related errors behind a pooler. Server-side cursors maintain state across queries and are not compatible with transaction pooling. See Django's documentation.

Advanced Settings​

  • AUTHENTIK_POSTGRESQL__DEFAULT_SCHEMA

    Database schema used by authentik.

    Default: public

    This can only be set before authentik starts for the first time. If you use a custom schema:

    • the schema must already exist
    • the PostgreSQL user must have permission to use it
    • the user's search_path must include that schema

  • AUTHENTIK_POSTGRESQL__CONN_OPTIONS

    Additional libpq connection parameters for the primary database connection.

    A list of supported parameter keywords can be found in the PostgreSQL documentation.

    • Parameters passed with this setting will override those passed with other settings.
    • These parameters are not applied to read replicas.
    • The value must be a base64-encoded JSON dictionary.

Read Replicas​

authentik can send read queries to replica databases while keeping writes on the primary database.

When replicas are configured, authentik prefers replicas for query traffic. If you also want the primary database to serve reads, configure it as a replica too.

Each replica uses the same setting structure as the primary connection, but under READ_REPLICAS.

For the first replica, use index 0:

  • AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__HOST
  • AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__NAME
  • AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__USER
  • AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__PORT
  • AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__PASSWORD
  • AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__SSLMODE
  • AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__SSLROOTCERT
  • AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__SSLCERT
  • AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__SSLKEY
  • AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__CONN_MAX_AGE
  • AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__CONN_HEALTH_CHECKS
  • AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__DISABLE_SERVER_SIDE_CURSORS
  • AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__CONN_OPTIONS

Use index 1, 2, and so on for additional replicas.

To apply additional libpq parameters to all replicas, use:

  • AUTHENTIK_POSTGRESQL__REPLICA_CONN_OPTIONS

    Additional libpq connection parameters for all read replica connections.

    A list of supported keywords can be found in the PostgreSQL documentation.

    • Parameters passed with this setting will override those passed with other settings.
    • The value must be a base64-encoded JSON dictionary.

Using a PostgreSQL Connection Pooler​

If authentik connects through a pooler such as PgBouncer or Pgpool, review these settings carefully:

  • AUTHENTIK_POSTGRESQL__CONN_MAX_AGE

    Session-based pooling can behave poorly with unlimited persistent connections (null). If the pooler drops its backend connection while the client connection remains open, the connection may not be released as expected.

    To avoid this, either:

    • use transaction pooling, or
    • set CONN_MAX_AGE lower than the timeout that causes backend connections to be dropped, including 0 to disable persistent connections

  • AUTHENTIK_POSTGRESQL__DISABLE_SERVER_SIDE_CURSORS

    When using transaction pooling, set this to true. Server-side cursors keep state across queries and will break when subsequent queries are sent over different backend connections.

These are good starting points for common deployments:

  • Direct PostgreSQL connection:
    • leave AUTHENTIK_POSTGRESQL__CONN_MAX_AGE at 0
    • leave AUTHENTIK_POSTGRESQL__DISABLE_SERVER_SIDE_CURSORS at false
  • PgBouncer or Pgpool in transaction mode:
    • set AUTHENTIK_POSTGRESQL__DISABLE_SERVER_SIDE_CURSORS=true
    • keep AUTHENTIK_POSTGRESQL__CONN_MAX_AGE=0 unless you have a reason to change it
  • TLS-secured PostgreSQL:
    • keep AUTHENTIK_POSTGRESQL__SSLMODE=verify-ca or use verify-full if hostname verification is available

Deprecated Settings​

Cache Settings​

  • 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

Worker settings​

AUTHENTIK_WORKER__PROCESSES​

Configure how many worker processes should be started for Dramatiq to use. In environments where scaling with multiple replicas of the authentik worker is not possible, this number can be increased to handle higher loads.

Defaults to 1. In environments where scaling with multiple replicas of the authentik worker is not possible, this number can be increased to handle higher loads.

AUTHENTIK_WORKER__THREADS​

Configure how many Dramatiq threads are started per worker. In environments where scaling with multiple replicas of the authentik worker is not possible, this number can be increased to handle higher loads.

Defaults to 2. A value below 2 threads is not recommended, unless you have multiple worker replicas.

AUTHENTIK_WORKER__CONSUMER_LISTEN_TIMEOUT​

Configure how long a worker waits for a PostgreSQL LISTEN notification.

Defaults to seconds=30.

AUTHENTIK_WORKER__TASK_MAX_RETRIES​

Configure how many times a failing task will be retried before abandoning.

Defaults to 5.

AUTHENTIK_WORKER__TASK_DEFAULT_TIME_LIMIT​

Configure the default duration a task can run for before it is aborted. Some tasks will override this setting based on other settings, such as LDAP source synchronization tasks.

Defaults to minutes=10.

AUTHENTIK_WORKER__TASK_PURGE_INTERVAL​

Configure the interval at which old tasks are cleaned up.

Defaults to days=1.

AUTHENTIK_WORKER__TASK_EXPIRATION​

Configure how long tasks are kept in the database before they are deleted.

Defaults to days=30.

AUTHENTIK_WORKER__SCHEDULER_INTERVAL​

Configure how often the task scheduler runs.

Defaults to seconds=60.

Listen Settings​

AUTHENTIK_LISTEN__HTTP​

List of comma-separated address:port values for HTTP.

Applies to the Server, the Worker, and Proxy outposts.

Defaults to [::]:9000.

AUTHENTIK_LISTEN__HTTPS​

List of comma-separated address:port values for HTTPS.

Applies to the Server and Proxy outposts.

Defaults to [::]:9443.

AUTHENTIK_LISTEN__LDAP​

List of comma-separated address:port values for LDAP.

Applies to LDAP outposts.

Defaults to [::]:3389.

AUTHENTIK_LISTEN__LDAPS​

List of comma-separated address:port values for LDAPS.

Applies to LDAP outposts.

Defaults to [::]:6636.

AUTHENTIK_LISTEN__METRICS​

List of comma-separated address:port values for Prometheus metrics.

Applies to all.

Defaults to [::]:9300.

AUTHENTIK_LISTEN__DEBUG​

Listening address:port for Go Debugging metrics.

Applies to all, except the worker.

Defaults to 0.0.0.0:9900.

AUTHENTIK_LISTEN__DEBUG_PY​

Listening address:port for Python debugging server, see Debugging.

Applies to the Server and the Worker.

Defaults to 0.0.0.0:9901.

AUTHENTIK_LISTEN__TRUSTED_PROXY_CIDRS​

List of comma-separated CIDRs that proxy headers should be accepted from.

Applies to the Server.

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.

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.

Storage settings​

These settings affect where files are stored. By default, they are stored on disk in the /data directory of the authentik container. S3 storage is also supported.

AUTHENTIK_STORAGE__BACKEND​

This parameter defines where to store files. Valid values are file and s3. For file storage, files are stored in a /data directory in the container. For s3, see below.

Defaults to file.

File storage backend settings​

AUTHENTIK_STORAGE__FILE__PATH​

Where to store files on disk.

Defaults to /data.

AUTHENTIK_STORAGE__FILE__URL_EXPIRY​

How long generated URLs for file access are valid for.

Defaults to minutes=15.

S3 storage backend settings​

For more information on S3 storage, see S3 storage setup.

AUTHENTIK_STORAGE__S3__REGION​

S3 region where the bucket has been created. May be omitted depending on which S3 provider you use.

Defaults to not set.

AUTHENTIK_STORAGE__S3__ENDPOINT​

Endpoint to use to talk to the S3 storage provider. Overrides the previous region and use_ssl settings.

Must be a valid URL in the form of https://s3.provider.

Defaults to not set.

AUTHENTIK_STORAGE__S3__USE_SSL​

Whether to use HTTPS when talking to the S3 storage providers.

Defaults to true.

AUTHENTIK_STORAGE__S3__ADDRESSING_STYLE​

Configure the addressing style used to address a bucket.

Valid values are auto and path.

Defaults to auto.

AUTHENTIK_STORAGE__S3__SIGNATURE_VERSION​

Configure the signing method used for S3 requests.

Defaults to s3v4.

Set to s3 for legacy S3-compatible providers that do not support signature v4.

AUTHENTIK_STORAGE__S3__SESSION_PROFILE​

Profile to use when using AWS SDK authentication.

Supports hot-reloading.

Defaults to not set.

AUTHENTIK_STORAGE__S3__ACCESS_KEY​

Access key to authenticate to S3. May be omitted if using AWS SDK authentication.

Supports hot-reloading.

Defaults to not set.

AUTHENTIK_STORAGE__S3__SECRET_KEY​

Secret key to authenticate to S3. May be omitted if using AWS SDK authentication.

Supports hot-reloading.

Defaults to not set.

AUTHENTIK_STORAGE__S3__SECURITY_TOKEN​

Security token to authenticate to S3. May be omitted.

Supports hot-reloading.

Defaults to not set.

AUTHENTIK_STORAGE__S3__BUCKET_NAME​

Name of the bucket to use to store files.

AUTHENTIK_STORAGE__S3__CUSTOM_DOMAIN​

Domain to use to create URLs for users. Mainly useful for non-AWS providers.

May include a port. Must include the bucket.

Example: s3.company:8080/authentik-data.

Defaults to not set.

AUTHENTIK_STORAGE__S3__SECURE_URLS​

Whether URLs created use HTTPS or HTTP.

Defaults to true.

AUTHENTIK_STORAGE__S3__URL_EXPIRY​

How long generated URLs for file access are valid for.

Defaults to minutes=15.

Media storage settings​

These settings affect where media files are stored. Those files include applications and sources icons.

AUTHENTIK_STORAGE__MEDIA__BACKEND​

Overrides AUTHENTIK_STORAGE__BACKEND

AUTHENTIK_STORAGE__MEDIA__FILE__[...]​

Overrides AUTHENTIK_STORAGE__FILE__[...] settings.

AUTHENTIK_STORAGE__MEDIA__S3__[...]​

Overrides AUTHENTIK_STORAGE__S3__[...] settings.

These settings affect where media files are stored. Those files include applications and sources icons. By default, they use the same storage settings as the main storage configuration. S3 storage is also supported.

Reports storage settings​

These settings affect where CSV reports are stored.

AUTHENTIK_STORAGE__REPORTS__BACKEND​

Overrides AUTHENTIK_STORAGE__BACKEND

AUTHENTIK_STORAGE__REPORTS__FILE__[...]​

Overrides AUTHENTIK_STORAGE__FILE__[...] settings.

AUTHENTIK_STORAGE__REPORTS__S3__[...]​

Overrides AUTHENTIK_STORAGE__S3__[...] settings.

authentik Settings​

AUTHENTIK_SECRET_KEY​

Secret key used for cookie signing. Changing this will invalidate active sessions.

caution

Prior to 2023.6.0 the secret key was also used for unique user IDs. When running a pre-2023.6.0 version of authentik the key should not be changed 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 effect 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.

Which domain the session cookie should be set to. By default, the cookie is set to the domain authentik is accessed under.

AUTHENTIK_EVENTS__CONTEXT_PROCESSORS__GEOIP​

Path to the GeoIP City database. Defaults to /geoip/GeoLite2-City.mmdb. If the file is not found, authentik will skip GeoIP support.

AUTHENTIK_EVENTS__CONTEXT_PROCESSORS__ASN​

Path to the GeoIP ASN database. Defaults to /geoip/GeoLite2-ASN.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 email address.

  • AUTHENTIK_ERROR_REPORTING__SEND_PII

    Whether or not to send personal data, like usernames. Defaults to false.

  • AUTHENTIK_ERROR_REPORTING__EXTRA_ARGS

    Base64-encoded sentry_init arguments. See Sentry's documentation for available options.

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_LDAP__TASK_TIMEOUT_HOURS​

Timeout in hours for LDAP synchronization tasks.

Defaults to 2.

AUTHENTIK_LDAP__PAGE_SIZE​

Page size for LDAP synchronization. Controls the number of objects created in a single task.

Defaults to 50.

AUTHENTIK_LDAP__TLS__CIPHERS​

Allows configuration of TLS Ciphers for LDAP connections used by LDAP sources. Setting applies to all sources.

Defaults to null.

AUTHENTIK_REPUTATION__EXPIRY​

Configure how long reputation scores should be saved for in seconds.

Defaults to 86400.

AUTHENTIK_SESSION_STORAGE​

Deprecated

This setting is removed as of version 2025.4. Sessions are now exclusively stored in the database. See our 2025.4 release notes for more information.

If you are running a version earlier than 2025.4, you can configure if the sessions are stored in the cache or the database. Defaults to cache. Allowed values are cache and db. Note that changing this value will invalidate all previous sessions.

AUTHENTIK_SESSIONS__UNAUTHENTICATED_AGEauthentik: 2025.4.0+​

Configure how long unauthenticated sessions last for. Does not impact how long authenticated sessions are valid for. See the user login stage for session validity.

Defaults to days=1.

AUTHENTIK_WEB__WORKERS​

Configure how many gunicorn worker processes should be started (see https://docs.gunicorn.org/en/stable/design.html).

Defaults to 2. A value below 2 workers is not recommended. In environments where scaling with multiple replicas of the authentik server is not possible, this number can be increased to handle higher loads.

AUTHENTIK_WEB__THREADS​

Configure how many gunicorn threads a worker processes should have (see https://docs.gunicorn.org/en/stable/design.html).

Defaults to 4.

AUTHENTIK_WEB__MAX_REQUESTS​

The maximum number of requests a worker will process before restarting. If this is set to zero then the automatic worker restarts are disabled (see https://gunicorn.org/reference/settings/#max_requests).

Defaults to 1000.

AUTHENTIK_WEB__MAX_REQUESTS_JITTER​

The maximum jitter to add to the AUTHENTIK_WEB__MAX_REQUESTS setting (see https://gunicorn.org/reference/settings/#max_requests_jitter).

Defaults to 50.

AUTHENTIK_WEB__PATH​

Configure the path under which authentik is served. For example to access authentik under https://my.domain/authentik/, set this to /authentik/. Value must contain both a leading and trailing slash.

Defaults to /.

AUTHENTIK_WEB__TIMEOUT_HTTP​

Configure the timeouts for the web HTTP/HTTPS Server. Accepts duration in the format of "300ms", "-1.5h" or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".

  • AUTHENTIK_WEB__TIMEOUT_HTTP_READ_HEADER

Defaults to 5s

  • AUTHENTIK_WEB__TIMEOUT_HTTP_READ

Defaults to 30s

  • AUTHENTIK_WEB__TIMEOUT_HTTP_WRITE

Defaults to 60s

  • AUTHENTIK_WEB__TIMEOUT_HTTP_IDLE

Defaults to 120s

Advanced settings​

AUTHENTIK_SKIP_MIGRATIONS​

Whether to skip running migrations on starting authentik. This is destined to advanced setups and not recommended in normal use.

Defaults to false.

System settings​

Additional system settings are configurable using the Admin interface, under System > Settings or using the API.

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

caution

Using these custom settings is not supported and can prevent your authentik instance from starting. Use with caution.