File - Authelia — ContextQMD

Configuration

yaml

authentication_backend:
  file:
    path: '/config/users.yml'
    watch: false
    search:
      email: false
      case_insensitive: false
    extra_attributes:
      extra_example:
        multi_valued: false
        value_type: 'string'
    password:
      algorithm: 'argon2'
      argon2:
        variant: 'argon2id'
        iterations: 3
        memory: 65536
        parallelism: 4
        key_length: 32
        salt_length: 16
      scrypt:
        variant: '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

Options

This section describes the individual configuration options.

path

The path to the file with the user details list. Supported file types are:

YAML File

watch

Enables reloading the database by watching it for changes.

search {#config-search}

Username searching functionality options.

{{< callout context="caution" title="Important Note" icon="outline/alert-triangle" >}} This functionality is experimental. {{< /callout >}}

email

{{< callout context="note" title="Note" icon="outline/info-circle" >}} Emails are always checked using case-insensitive lookup. {{< /callout >}}

Allows users to login using their email address. If enabled two users must not have the same emails and their usernames must not be an email.

case_insensitive

{{< callout context="note" title="Note" icon="outline/info-circle" >}} Emails are always checked using case-insensitive lookup. {{< /callout >}}

Enabling this search option allows users to login with their username regardless of case. If enabled users must only have lowercase usernames.

extra_attributes

{{< callout context="note" title="Note" icon="outline/info-circle" >}} In addition to the extra attributes, you can configure custom attributes based on the values of existing attributes. This is done via the Definitions section. {{< /callout >}}

The extra attributes to load from the directory server. These extra attributes can be used in other areas of Authelia such as OpenID Connect 1.0. It's also recommended to check out the Attributes Reference Guide for more information.

The key represents the backend attribute name. The database will be validated given the multi_valued and value_type configuration.

In the example below, we load the directory server attribute example_file_attribute into the Authelia attribute example_file_attribute, treat it as a single valued attribute which has an underlying type of integer.

yaml

authentication_backend:
  file:
    extra_attributes:
      example_file_attribute:
        multi_valued: false
        value_type: 'integer'

value_type

This defines the underlying type the attribute must be. This is required if an extra attribute is configured. The valid values are string, integer, or boolean.

multi_valued

This indicates the underlying type can have multiple values.

Password Options

A reference guide exists specifically for choosing password hashing values. This section contains far more information than is practical to include in this configuration document. See the Passwords Reference Guide for more information.

This guide contains examples such as the User / Password File.

algorithm

Controls the hashing algorithm used for hashing new passwords. Value must be one of:

argon2 for the Argon2 algorithm
scrypt for the Scrypt algorithm
pbkdf2 for the PBKDF2 algorithm
sha2crypt for the SHA2Crypt algorithm
bcrypt for the Bcrypt algorithm

argon2

The Argon2 algorithm implementation. This is one of the only algorithms that was designed purely with password hashing in mind and is subsequently one of the best algorithms to date for security.

variant

Controls the variant when hashing passwords using Argon2. Recommended argon2id. Permitted values argon2id, argon2i, argon2d.

iterations

Controls the number of iterations when hashing passwords using Argon2.

memory

Controls the amount of memory in kibibytes when hashing passwords using Argon2.

parallelism

Controls the parallelism factor when hashing passwords using Argon2.

key_length

Controls the output key length when hashing passwords using Argon2.

salt_length

Controls the output salt length when hashing passwords using Argon2.

scrypt

The Scrypt algorithm implementation.

variant

Controls the variant when hashing passwords using Scrypt. Permitted values scrypt, yescrypt.

iterations

Controls the number of iterations when hashing passwords using Scrypt.

block_size

Controls the block size when hashing passwords using Scrypt.

parallelism

Controls the parallelism factor when hashing passwords using Scrypt.

key_length

Controls the output key length when hashing passwords using Scrypt.

salt_length

Controls the output salt length when hashing passwords using Scrypt.

pbkdf2

The PBKDF2 algorithm implementation.

variant

Controls the variant when hashing passwords using PBKDF2.

The below table has the supported variants, information on NIST FIPS 140 compliance status. Compliant means it's been formally tested by a NIST accredited laboratory, Approved means it should theoretically become Compliant when formally tested by a NIST accredited laboratory.

iterations

Controls the number of iterations when hashing passwords using PBKDF2.

The default value is based on the variant as described in the below table. These values are slightly higher than the FIPS 140 recommendations for future proofing.

salt_length

Controls the output salt length when hashing passwords using PBKDF2.

sha2crypt

The SHA2 Crypt algorithm implementation.

variant

Controls the variant when hashing passwords using SHA2 Crypt. Recommended sha512. Permitted values sha256, sha512.

iterations

Controls the number of iterations when hashing passwords using SHA2 Crypt.

salt_length

Controls the output salt length when hashing passwords using SHA2 Crypt.

bcrypt

The Bcrypt algorithm implementation.

variant

Controls the variant when hashing passwords using Bcrypt. Recommended standard. Permitted values standard, sha256.

{{< callout context="caution" title="Important Note" icon="outline/alert-triangle" >}} The sha256 variant is a special variant designed by Passlib. This variant passes the password through a SHA256 HMAC before passing it to the Bcrypt algorithm, effectively bypassing the 72 byte password truncation that Bcrypt does. It is not supported by many other systems. {{< /callout >}}

cost

Controls the hashing cost when hashing passwords using Bcrypt.