Passwords

User / Password File#

This file should be set with read/write permissions as it could be updated by users resetting their passwords.

YAML Format#

The format of the YAML file is as follows:

users:
  john:
    disabled: false
    displayname: 'John Doe'
    password: '$argon2id$v=19$m=65536,t=3,p=2$BpLnfgDsc2WD8F2q$o/vzA4myCqZZ36bUGsDY//8mKUYNZZaR0t4MFFSs+iM'
    email: 'john.doe@authelia.com'
    groups:
      - 'admins'
      - 'dev'
  harry:
    disabled: false
    displayname: 'Harry Potter'
    password: '$argon2id$v=19$m=65536,t=3,p=2$BpLnfgDsc2WD8F2q$o/vzA4myCqZZ36bUGsDY//8mKUYNZZaR0t4MFFSs+iM'
    email: 'harry.potter@authelia.com'
    groups: []
  bob:
    disabled: false
    displayname: 'Bob Dylan'
    password: '$argon2id$v=19$m=65536,t=3,p=2$BpLnfgDsc2WD8F2q$o/vzA4myCqZZ36bUGsDY//8mKUYNZZaR0t4MFFSs+iM'
    email: 'bob.dylan@authelia.com'
    groups:
      - 'dev'
  james:
    disabled: false
    displayname: 'James Dean'
    password: '$argon2id$v=19$m=65536,t=3,p=2$BpLnfgDsc2WD8F2q$o/vzA4myCqZZ36bUGsDY//8mKUYNZZaR0t4MFFSs+iM'
    email: 'james.dean@authelia.com'
    groups: []

Passwords#

The file contains hashed passwords instead of plain text passwords for security reasons.

You can use Authelia binary or docker image to generate the hash of any password. The crypt hash generate command has many supported algorithms. To view them run the authelia crypto hash generate --help command. To see the tunable options for an algorithm subcommand include that command before --help. For example for the Argon2 algorithm use the authelia crypto hash generate argon2 --help command to see the available options.

Passwords passed to crypt hash generate should be single quoted if using the --password parameter instead of the console prompt, especially if it has special characters to prevent parameter substitution.

To generate an Argon2 hash with the docker image interactively just run:

docker run --rm -it authelia/authelia:latest authelia crypto hash generate argon2

authelia crypto hash generate argon2

To generate an Argon2 hash with the docker image without a prompt you can run:

docker run --rm authelia/authelia:latest authelia crypto hash generate argon2 --password 'password'

authelia crypto hash generate argon2 --password 'password'

Output Example:

Digest: $argon2id$v=19$m=65536,t=3,p=4$Hjc8e7WYcBFcJmEDUOsS9A$ozM7RyZR1EyDR8cuyVpDDfmLrGPGFgo5E2NNqRumui4

You may also use the --config flag to point to your existing configuration. When used, the values defined in the config will be used instead. For example to generate the password with a configuration file named configuration.yml in the current directory:

docker run --rm -it -v ./configuration.yml:/configuration.yml authelia/authelia:latest authelia crypto hash generate --config /configuration.yml

authelia crypto hash generate --config /configuration.yml

Output Example:

Enter Password:
Confirm Password:

Digest: $argon2id$v=19$m=65536,t=3,p=4$Hjc8e7WYcBFcJmEDUOsS9A$ozM7RyZR1EyDR8cuyVpDDfmLrGPGFgo5E2NNqRumui4

See the full CLI reference documentation.

Cost#

The most important part about choosing a password hashing function is the cost. It’s generally recommended that the cost takes roughly 500 milliseconds on your hardware to complete, however if you have very old hardware you may want to consider more than 500 milliseconds, or if you have really high end hardware you may want to consider slightly less depending on if you have a large quantity of users.

Ideally on average hardware the amount of time would be roughly 500 milliseconds at minimum.

In consideration of your cost you should take into account the fact some algorithms only support scaling the cost for one factor and not others It’s usually considered better to have a mix of cost types however this is not possible with all algorithms. The main cost type measurements are:

• CPU
• Memory

To get a rough estimate of how much memory should be utilized with these algorithms you can utilize the following command:

stress-ng --vm-bytes $(awk '/MemFree/{printf "%d\n", $2 * 0.9;}' < /proc/meminfo)k --vm-keep -m 1

If this is not desirable we recommend investigating the following options in order of most to least secure:

1. Use the LDAP authentication provider instead
2. Adjusting the memory parameter
3. Changing the algorithm

Algorithms#

The default hash algorithm is the Argon2 id variant version 19 with a salt. Argon2 is at the time of this writing widely considered to be the best hashing algorithm, and in 2015 won the Password Hashing Competition. It benefits from customizable parameters including a memory parameter allowing the cost of computing a hash to scale into the future with better hardware which makes it harder to brute-force.

For backwards compatibility and user choice support for the SHA2 Crypt algorithm (SHA512 variant) is still available. While it’s a reasonable hashing function given high enough iterations, as hardware improves it has a higher chance of being brute-forced since it only allows scaling the CPU cost whereas Argon2 allows scaling both for CPU and Memory cost.

Identification#

The algorithm that a hash is utilizing is identifiable by its prefix:

See the Crypt (C) Wiki page for more information.

Tuning#

The configuration variables are unique to the file authentication provider, thus they all exist in a key under the file authentication configuration key called password. The defaults are considered as sane for a reasonable system however we still recommend taking time to figure out the best values to adequately determine the cost.

While there are recommended parameters for each algorithm it’s your responsibility to tune these individually for your particular system. We strongly recommend reading other sources such as the OWASP Cheat Sheet when tuning these algorithms.

Algorithm Choice#

We generally discourage Bcrypt except when needed for interoperability with legacy systems. The argon2id variant of the Argon2 algorithm is the best choice of the algorithms available, but it’s important to note that the argon2id variant is the most resilient variant, followed by the argon2d variant and the argon2i variant not being recommended. It’s strongly recommended if you’re unsure that you use argon2id. Scrypt is a likely second best algorithm. PBKDF2 is practically the only choice when it comes to FIPS-140 compliance. The sha512 variant of the SHA2 Crypt algorithm is also a reasonable option, but is mainly available for backwards compatibility.

All other algorithms and variants available exist only for interoperability and we discourage their use if a better algorithm is available in your scenario.

Recommended Parameters: Argon2#

This table adapts the RFC9106 Parameter Choice recommendations to our configuration options:

Recommended Parameters: SHA2 Crypt#

This table suggests the parameters for the SHA2 Crypt algorithm: