authelia/docs/configuration/authentication/file.md

layout	title	parent	grand_parent	nav_order
default	File	Authentication backends	Configuration	1

File

Authelia supports a file as a users database.

Configuration

Configuring Authelia to use a file is done by specifying the path to the file in the configuration file.

authentication_backend:
  # Disable both the HTML element and the API for reset password functionality
  disable_reset_password: false

  # File backend configuration.
  #
  # 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://docs.authelia.com/configuration/authentication/file.html#password-hash-algorithm-tuning

  file:
    path: /config/users.yml
    password:
      algorithm: argon2id
      iterations: 1
      salt_length: 16
      parallelism: 8
      memory: 64

Format

The format of the users file is as follows.

users:
  john:
    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:
    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:
    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:
    displayname: "James Dean"
    password: "$argon2id$v=19$m=65536,t=3,p=2$BpLnfgDsc2WD8F2q$o/vzA4myCqZZ36bUGsDY//8mKUYNZZaR0t4MFFSs+iM"
    email: james.dean@authelia.com

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

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 hash-password command has many tunable options, you can view them with the authelia hash-password --help command. For example if you wanted to improve the entropy you could generate a 16 byte salt and provide it with the --salt flag. Example: authelia hash-password --salt abcdefghijklhijl. For argon2id the salt must always be valid for base64 decoding (characters a through z, A through Z, 0 through 9, and +/).

Passwords passed to hash-password should be single quoted if using special characters to prevent parameter substitution. For instance to generate a hash with the docker image just run:

$ docker run authelia/authelia:latest authelia hash-password 'yourpassword'
Password hash: $argon2id$v=19$m=65536$3oc26byQuSkQqksq$zM1QiTvVPrMfV6BVLs2t4gM+af5IN7euO0VB6+Q8ZFs

Full CLI Help Documentation:

Hash a password to be used in file-based users database. Default algorithm is argon2id.

Usage:
  authelia hash-password [password] [flags]

Flags:
  -h, --help              help for hash-password
  -i, --iterations int    set the number of hashing iterations (default 1)
  -k, --key-length int    [argon2id] set the key length param (default 32)
  -m, --memory int        [argon2id] set the amount of memory param (in MB) (default 64)
  -p, --parallelism int   [argon2id] set the parallelism param (default 8)
  -s, --salt string       set the salt string
  -l, --salt-length int   set the auto-generated salt length (default 16)
  -z, --sha512            use sha512 as the algorithm (defaults iterations to 50000, change with -i)

Password hash algorithm

The default hash algorithm is Argon2id version 19 with a salt. Argon2id is currently considered the best hashing algorithm, and in 2015 won the Password Hashing Competition. It benefits from customizable parameters allowing the cost of computing a hash to scale into the future which makes it harder to brute-force. Argon2id was implemented due to community feedback as you can see in this closed issue.

For backwards compatibility and user choice support for the SHA512 algorithm 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.

Hashes are identifiable as argon2id or SHA512 by their prefix of either $argon2id$ and $6$ respectively, as described in this wiki page.

Important Note: When using argon2id Authelia will appear to remain using the memory allocated to creating the hash. This is due to how Go allocates memory to the heap when generating an argon2id hash. Go periodically garbage collects the heap, however this doesn't remove the memory allocation, it keeps it allocated even though it's technically unused. Under memory pressure the unused allocated memory will be reclaimed by the operating system, you can test this on linux with:

$ 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. using the LDAP authentication provider
2. adjusting the memory parameter
3. changing the algorithm

Password hash algorithm tuning

All algorithm tuning for Argon2id is supported. The only configuration variables that affect SHA512 are iterations and salt length. 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. We have set what are considered as sane and recommended defaults to cater for a reasonable system, if you're unsure about which settings to tune, please see the parameters below, or for a more in depth understanding see the referenced documentation in Argon2 links.

Password hashing configuration settings

algorithm

• Value Type: String
• Possible Value: argon2id or sha512
• Recommended: argon2id
• What it Does: Changes the hashing algorithm

iterations

• Value Type: Int
• Possible Value: 1 or higher for argon2id and 1000 or higher for sha512 (will automatically be set to 1000 on lower settings)
• Recommended: 1 for the argon2id algorithm and 50000 for sha512
• What it Does: Adjusts the number of times we run the password through the hashing algorithm

key_length

• Value Type: Int
• Possible Value: 16 or higher.
• Recommended: 32 or higher.
• What it Does: Adjusts the length of the actual hash

salt_length

• Value Type: Int
• Possible Value: 8 or higher.
• Recommended: 16
• What it Does: Adjusts the length of the random salt we add to the password, there is no reason not to set this to 16

parallelism

• Value Type: Int
• Possible Value: 1 or higher
• Recommended: 8 or twice your CPU cores
• What it Does: Sets the number of threads used for hashing

memory

• Value Type: Int
• Possible Value: at least 8 times the value of parallelism
• Recommended: 64 (64MB) or as much RAM as you can afford to give to hashing
• What it Does: Sets the amount of RAM used in MB for hashing

Examples for specific systems

These examples have been tested against a single system to make sure they roughly take 0.5 seconds each. Your results may vary depending on individual specification and utilization, but they are a good guide to get started. You should however read the linked documents in Argon2 links.

System	Iterations	Parallelism	Memory
Raspberry Pi 2	1	8	64
Raspberry Pi 3	1	8	128
Raspberry Pi 4	1	8	128
Intel G5 i5 NUC	1	8	1024

Argon2 Links

How to choose the right parameters for Argon2

Go Documentation

IETF Draft