---
obj: application
website: https://www.authelia.com
repo: https://github.com/authelia/authelia
---

# Authelia
Authelia is an open-source authentication and authorization server and portal fulfilling the identity and access management (IAM) role of information security in providing multi-factor authentication and single sign-on (SSO) for your applications via a web portal. It acts as a companion for common reverse proxies.

## Docker-Compose
```
version: "3"

services:
  authelia:
    image: authelia/authelia
    volumes:
      - ./authelia:/config
    ports:
        # Web Interface
      - 9091:9091
    restart: unless-stopped
    environment:
      - TZ=Europe/Berlin
    depends_on:
      - redis

  redis:
    image: redis:alpine
    volumes:
      - ./redis:/data
    restart: unless-stopped
    environment:
      - TZ=Europe/Berlin
```

## Authelia Configuration
The configuration is done via a [YAML](../../files/YAML.md) file.

Sample Configuration:
```yml
## Note: the container by default expects to find this file at /config/configuration.yml.

## The theme to display: light, dark, grey, auto.
theme: light

## The secret used to generate JWT tokens when validating user identity by email confirmation.
jwt_secret: a_very_important_secret

## Default redirection URL
##
## If user tries to authenticate without any referer, Authelia does not know where to redirect the user to at the end of the authentication process. This parameter allows you to specify the default redirection URL Authelia will use in such a case.
##
## Note: this parameter is optional. If not provided, user won't be redirected upon successful authentication.
default_redirection_url: https://home.example.com/

## Set the default 2FA method for new users and for when a user has a preferred method configured that has been disabled. This setting must be a method that is enabled.
## Options are totp, webauthn, mobile_push.
default_2fa_method: ""

## Server Configuration
server:

  ## The address to listen on.
  host: 0.0.0.0

  ## The port to listen on.
  port: 9091

  ## Set the single level path Authelia listens on.
  ## Must be alphanumeric chars and should not contain any slashes.
  path: ""

  ## Set the path on disk to Authelia assets.
  ## Useful to allow overriding of specific static assets.
  asset_path: /config/assets/

  ## Enables the pprof endpoint.
  enable_pprof: false

  ## Enables the expvars endpoint.
  enable_expvars: false


## Log Configuration
log:
  ## Level of verbosity for logs: info, debug, trace.
  level: debug

  ## Format the logs are written as: json, text.
  format: json

  ## File path where the logs will be written. If not set logs are written to stdout.
  file_path: /config/authelia.log

  ## Whether to also log to stdout when a log_file_path is defined.
  keep_stdout: false


## Telemetry Configuration
telemetry:

  ## Metrics Configuration
  metrics:
    ## Enable Metrics.
    enabled: false

    ## The address to listen on for metrics. This should be on a different port to the main server.port value.
    address: tcp://0.0.0.0:9959

## TOTP Configuration
## Parameters used for TOTP generation.
totp:
  ## Disable TOTP.
  disable: false

  ## The issuer name displayed in the Authenticator application of your choice.
  issuer: authelia.com

  ## The TOTP algorithm to use.
  ## It is CRITICAL you read the documentation before changing this option:
  ## https://www.authelia.com/c/totp#algorithm
  algorithm: sha1

  ## The number of digits a user has to input. Must either be 6 or 8.
  ## Changing this option only affects newly generated TOTP configurations.
  ## It is CRITICAL you read the documentation before changing this option:
  ## https://www.authelia.com/c/totp#digits
  digits: 6

  ## The period in seconds a one-time password is valid for.
  ## Changing this option only affects newly generated TOTP configurations.
  period: 30

  ## The skew controls number of one-time passwords either side of the current one that are valid.
  ## Warning: before changing skew read the docs link below.
  skew: 1
  ## See: https://www.authelia.com/c/totp#input-validation to read
  ## the documentation.

  ## The size of the generated shared secrets. Default is 32 and is sufficient in most use cases, minimum is 20.
  secret_size: 32


## WebAuthn Configuration
## Parameters used for WebAuthn.
webauthn:
  ## Disable Webauthn.
  disable: false

  ## Adjust the interaction timeout for Webauthn dialogues.
  timeout: 60s

  ## The display name the browser should show the user for when using Webauthn to login/register.
  display_name: Authelia

  ## Conveyance preference controls if we collect the attestation statement including the AAGUID from the device.
  ## Options are none, indirect, direct.
  attestation_conveyance_preference: indirect

  ## User verification controls if the user must make a gesture or action to confirm they are present.
  ## Options are required, preferred, discouraged.
  user_verification: preferred


## NTP Configuration
## This is used to validate the servers time is accurate enough to validate TOTP.
ntp:
  ## NTP server address.
  address: "time.cloudflare.com:123"

  ## NTP version.
  version: 4

  ## Maximum allowed time offset between the host and the NTP server.
  max_desync: 3s

  ## Disables the NTP check on startup entirely. This means Authelia will not contact a remote service at all if you
  ## set this to true, and can operate in a truly offline mode.
  disable_startup_check: false

  ## The default of false will prevent startup only if we can contact the NTP server and the time is out of sync with
  ## the NTP server more than the configured max_desync. If you set this to true, an error will be logged but startup
  ## will continue regardless of results.
  disable_failure: false


## Authentication Backend Provider Configuration
##
## Used for verifying user passwords and retrieve information such as email address and groups users belong to.
##
## The available providers are: `file`, `ldap`. You must use only one of these providers.
authentication_backend:

  ## Password Reset Options.
  password_reset:
    ## Disable both the HTML element and the API for reset password functionality.
    disable: false

    ## External reset password url that redirects the user to an external reset portal. This disables the internal reset
    ## functionality.
    custom_url: ""

  ## The amount of time to wait before we refresh data from the authentication backend. Uses duration notation.
  ## To disable this feature set it to 'disable', this will slightly reduce security because for Authelia, users will
  ## always belong to groups they belonged to at the time of login even if they have been removed from them in LDAP.
  ## To force update on every request you can set this to '0' or 'always', this will increase processor demand.
  refresh_interval: 5m

  ## File (Authentication Provider)
  ## With this backend, the users database is stored in a file which is updated when users reset their passwords.
  ## Therefore, this backend is meant to be used in a dev environment and not in production since it prevents Authelia
  ## to be scaled to more than one instance. The options under 'password' have sane defaults, and as it has security
  ## implications it is highly recommended you leave the default values. Before considering changing these settings
  ## please read the docs page below:
  ## https://www.authelia.com/r/passwords#tuning
  file:
    path: /config/users_database.yml
    watch: false
    search:
      email: false
      case_insensitive: false
    password:
      algorithm: argon2
      argon2:
        variant: argon2id
        iterations: 3
        memory: 65536
        parallelism: 4
        key_length: 32
        salt_length: 16
      scrypt:
        iterations: 16
        block_size: 8
        parallelism: 1
        key_length: 32
        salt_length: 16
      pbkdf2:
        variant: sha512
        iterations: 310000
        salt_length: 16
      sha2crypt:
        variant: sha512
        iterations: 50000
        salt_length: 16
      bcrypt:
        variant: standard
        cost: 12


## Password Policy Configuration.
password_policy:

  ## The standard policy allows you to tune individual settings manually.
  standard:
    enabled: false

    ## Require a minimum length for passwords.
    min_length: 8

    ## Require a maximum length for passwords.
    max_length: 0

    ## Require uppercase characters.
    require_uppercase: true

    ## Require lowercase characters.
    require_lowercase: true

    ## Require numeric characters.
    require_number: true

    ## Require special characters.
    require_special: true

  ## zxcvbn is a well known and used password strength algorithm. It does not have tunable settings.
  zxcvbn:
    enabled: false

    ## Configures the minimum score allowed.
    min_score: 3


## Access Control Configuration
##
## Access control is a list of rules defining the authorizations applied for one resource to users or group of users.
##
## If 'access_control' is not defined, ACL rules are disabled and the 'bypass' rule is applied, i.e., access is allowed
## to anyone. Otherwise restrictions follow the rules defined.
##
## Note: One can use the wildcard * to match any subdomain.
## It must stand at the beginning of the pattern. (example: *.example.com)
##
## Note: You must put patterns containing wildcards between simple quotes for the YAML to be syntactically correct.
##
## Definition: A 'rule' is an object with the following keys: 'domain', 'subject', 'policy' and 'resources'.
##
## - 'domain' defines which domain or set of domains the rule applies to.
##
## - 'subject' defines the subject to apply authorizations to. This parameter is optional and matching any user if not
##    provided. If provided, the parameter represents either a user or a group. It should be of the form
##    'user:<username>' or 'group:<groupname>'.
##
## - 'policy' is the policy to apply to resources. It must be either 'bypass', 'one_factor', 'two_factor' or 'deny'.
##
## - 'resources' is a list of regular expressions that matches a set of resources to apply the policy to. This parameter
##   is optional and matches any resource if not provided.
##
## Note: the order of the rules is important. The first policy matching (domain, resource, subject) applies.
access_control:
  ## Default policy can either be 'bypass', 'one_factor', 'two_factor' or 'deny'. It is the policy applied to any resource if there is no policy to be applied to the user.
  default_policy: deny

  rules:
    ## Rules applied to everyone
    - domain: 'public.example.com'
      policy: bypass

    ## Domain Regex examples. Generally we recommend just using a standard domain.
    - domain_regex: '^(?P<User>\w+)\.example\.com$'
      policy: one_factor
    - domain_regex: '^(?P<Group>\w+)\.example\.com$'
      policy: one_factor
    - domain_regex:
       - '^appgroup-.*\.example\.com$'
       - '^appgroup2-.*\.example\.com$'
      policy: one_factor
    - domain_regex: '^.*\.example\.com$'
      policy: two_factor

    - domain:
        - 'secure.example.com'
        - 'private.example.com'
      policy: two_factor

    - domain: 'singlefactor.example.com'
      policy: one_factor

    ## Rules applied to 'admins' group
    - domain: 'mx2.mail.example.com'
      subject: 'group:admins'
      policy: deny

    - domain: '*.example.com'
      subject:
        - 'group:admins'
        - 'group:moderators'
      policy: two_factor

    ## Rules applied to 'dev' group
    - domain: 'dev.example.com'
      resources:
        - '^/groups/dev/.*$'
      subject: 'group:dev'
      policy: two_factor

    ## Rules applied to user 'john'
    - domain: 'dev.example.com'
      resources:
        - '^/users/john/.*$'
      subject: 'user:john'
      policy: two_factor


## Session Provider Configuration
##
## The session cookies identify the user once logged in.
## The available providers are: `memory`, `redis`. Memory is the provider unless redis is defined.
session:
  ## The name of the session cookie.
  name: authelia_session

  ## The domain to protect.
  ## Note: the authenticator must also be in that domain.
  ## If empty, the cookie is restricted to the subdomain of the issuer.
  domain: example.com

  ## Sets the Cookie SameSite value. Possible options are none, lax, or strict.
  ## Please read https://www.authelia.com/c/session#same_site
  same_site: lax

  ## The secret to encrypt the session data. This is only used with Redis / Redis Sentinel.
  secret: insecure_session_secret

  ## The value for expiration, inactivity, and remember_me_duration are in seconds or the duration notation format.
  ## All three of these values affect the cookie/session validity period. Longer periods are considered less secure because a stolen cookie will last longer giving attackers more time to spy or attack.

  ## The time before the cookie expires and the session is destroyed if remember me IS NOT selected.
  expiration: 1h

  ## The inactivity time before the session is reset. If expiration is set to 1h, and this is set to 5m, if the user does not select the remember me option their session will get destroyed after 1h, or after 5m since the last time Authelia detected user activity.
  inactivity: 5m

  ## The time before the cookie expires and the session is destroyed if remember me IS selected.
  ## Value of -1 disables remember me.
  remember_me_duration: 1M

  ## Redis Provider
  redis:
    host: 127.0.0.1
    port: 6379
    ## Use a unix socket instead
    host: /var/run/redis/redis.sock

    ## Username used for redis authentication. This is optional and a new feature in redis 6.0.
    username: authelia

    ## Password can also be set using a secret: https://www.authelia.com/c/secrets
    password: authelia

    ## This is the Redis DB Index https://redis.io/commands/select (sometimes referred to as database number, DB, etc).
    database_index: 0

    ## The maximum number of concurrent active connections to Redis.
    maximum_active_connections: 8

    ## The target number of idle connections to have open ready for work. Useful when opening connections is slow.
    minimum_idle_connections: 0


## Regulation Configuration
## This mechanism prevents attackers from brute forcing the first factor. It bans the user if too many attempts are made
## in a short period of time.
regulation:
  ## The number of failed login attempts before user is banned. Set it to 0 to disable regulation.
  max_retries: 3

  ## The time range during which the user can attempt login before being banned. The user is banned if the
  ## authentication failed 'max_retries' times in a 'find_time' seconds window. Find Time accepts duration notation.
  find_time: 2m

  ## The length of time before a banned user can login again. Ban Time accepts duration notation.
  ban_time: 5m


## Storage Provider Configuration
##
## The available providers are: `local`, `mysql`, `postgres`. You must use one and only one of these providers.
storage:
  ## The encryption key that is used to encrypt sensitive information in the database. Must be a string with a minimum
  ## length of 20. Please see the docs if you configure this with an undesirable key and need to change it, you MUST use
  ## the CLI to change this in the database if you want to change it from a previously configured value.
  encryption_key: you_must_generate_a_random_string_of_more_than_twenty_chars_and_configure_this

  ## Local (Storage Provider)
  ## This stores the data in a SQLite3 Database.
  ## This is only recommended for lightweight non-stateful installations.
  local:
    ## Path to the SQLite3 Database.
    path: /config/db.sqlite3

  ## MySQL / MariaDB (Storage Provider)
  # mysql:
    # host: 127.0.0.1
    # port: 3306
    # database: authelia
    # username: authelia
    # password: mypassword
    # timeout: 5s

  ## PostgreSQL (Storage Provider)
  # postgres:
    # host: 127.0.0.1
    # port: 5432
    # database: authelia
    # schema: public
    # username: authelia
    # password: mypassword
    # timeout: 5s


## Notification Provider
## Notifications are sent to users when they require a password reset, a Webauthn registration or a TOTP registration.
## The available providers are: filesystem, smtp. You must use only one of these providers.
notifier:
  ## You can disable the notifier startup check by setting this to true.
  disable_startup_check: false

  ## File System (Notification Provider)
  filesystem:
    filename: /config/notification.txt


  ## SMTP (Notification Provider)
  ## Use a SMTP server for sending notifications. Authelia uses the PLAIN or LOGIN methods to authenticate.
  ## [Security] By default Authelia will:
  ##   - force all SMTP connections over TLS including unauthenticated connections
  ##      - use the disable_require_tls boolean value to disable this requirement
  ##        (only works for unauthenticated connections)
  ##   - validate the SMTP server x509 certificate during the TLS handshake against the hosts trusted certificates
  ##     (configure in tls section)
  # smtp:
    ## The SMTP host to connect to.
    # host: 127.0.0.1

    ## The port to connect to the SMTP host on.
    # port: 1025

    ## The connection timeout.
    # timeout: 5s

    ## The username used for SMTP authentication.
    # username: test

    ## The password used for SMTP authentication.
    # password: password

    ## The sender is used to is used for the MAIL FROM command and the FROM header.
    ## If this is not defined and the username is an email, we use the username as this value. This can either be just
    ## an email address or the RFC5322 'Name <email address>' format.
    # sender: "Authelia <admin@example.com>"

    ## HELO/EHLO Identifier. Some SMTP Servers may reject the default of localhost.
    # identifier: localhost

    ## Subject configuration of the emails sent. {title} is replaced by the text from the notifier.
    # subject: "[Authelia] {title}"

    ## This address is used during the startup check to verify the email configuration is correct.
    ## It's not important what it is except if your email server only allows local delivery.
    # startup_check_address: test@authelia.com

    ## By default we require some form of TLS. This disables this check though is not advised.
    # disable_require_tls: false

    ## Disables sending HTML formatted emails.
    # disable_html_emails: false
```

### User Database
If you have choosen the file based authentification backend, you need to create a `users_database.yml` file. Every object under `users` represents another user. You need to specify a password hash, you can get the password hash with `docker run authelia/authelia:latest authelia hash-password SOMEPASSWORD`.

Example:
```yml
users:
  admin:
    displayname: "Administration"
    password: "$argon2id$v=19$m=65536,t=3,p=4$Me8Gxh6+NGUEWo5xrh8AeA$gt8iH0b1sPNNfXN1VVjHZU6MSWRuYYjhnu7QvDDxQBQ"
    email: admin@example.com
    groups:
      - admin
      - dev
      - work
```

## Configuration for [traefik](traefik.md)
```yml
http:
	middlewares:
		authelia:
			forwardAuth:
				address: "http://authelia:9091/api/verify?rd=https://yourdomain.com"
				trustForwardHeader: true
				authResponseHeaders:
					- "Remote-User"
					- "Remote-Groups"
					- "Remote-Name"
					- "Remote-Email"
```

