Learn Authelia - Authentication Backends

#Introduction

In episode 4 you were introduced to authentication_backend as one of the sections of configuration.yml. Episode 5 brings it to the surface: this is where Authelia looks for the answer to the most fundamental question — are the username and password the user typed really that user's?

Authelia offers three options: the file backend (a YAML-based user database), the LDAP backend (connecting to OpenLDAP or Active Directory), and the no-authentication mode. This choice determines how you manage users, and this episode will dissect all three until you can decide which fits your needs.

#The Three Types of Authentication Backends

#File Backend

The file backend is the simplest starting point and the best fit for a homelab. All users are defined in a single YAML file: users_database.yml.

#File Structure

users:
  joko:
    password: "$argon2id$v=19$m=65536,t=3,p=4$...salt...$...hash..."
    displayname: "Joko Susilo"
    email: joko@example.com
    groups:
      - admins
      - users
  sari:
    password: "$argon2id$v=19$m=65536,t=3,p=4$...salt...$...hash..."
    displayname: "Sari Wulandari"
    email: sari@example.com
    groups:
      - users

Each user has:

• password — an argon2id hash (not plaintext, not MD5 hash). Argon2id resists GPU attacks because it requires large memory and real computation time.
• displayname — display name, shown on the portal.
• email — used for notifications and password resets.
• groups — group membership, used in access control rules (for example subject with group:admins).

#Generating a Password Hash

You never write plaintext passwords in this file. The argon2id hash is generated with the authelia crypto hash generate command:

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

authelia crypto hash generate argon2

Password hash: $argon2id$v=19$m=65536,t=3,p=4$...$...

Paste that output into the password field in users_database.yml. Every time you change a password, generate a new hash and update the file — then validate and restart.

#Enabling the File Backend

In configuration.yml:

authentication_backend:
  file:
    path: /config/users_database.yml

Nothing else. Validate the configuration, restart, and the joko user can already log in at the portal.

#LDAP Backend

When users already live in a centralized directory — OpenLDAP, FreeIPA, or Active Directory — you don't want to duplicate the user list in a YAML file. The LDAP backend connects Authelia directly to that directory.

#Basic Configuration

authentication_backend:
  ldap:
    address: ldaps://ldap.example.com
    base_dn: dc=example,dc=com
    user: cn=admin,dc=example,dc=com
    password: from-environment-variable
    additional_users_dn: ou=users
    users_filter: (&(|({username_attribute}={input})({mail_attribute}={input}))(objectClass=person))
    additional_groups_dn: ou=groups
    groups_filter: (&(member={dn})(objectClass=groupOfNames))
    attributes:
      username: uid
      display_name: displayName
      mail: mail
      group_name: cn

Key points:

• address — use ldaps:// (LDAP over TLS) for encryption, or ldap:// with StartTLS.
• base_dn — the search starting point in the directory, usually the reverse of your domain (dc=example,dc=com).
• user + password — credentials of a "system account" allowed to search users; don't use the main admin, and inject the password via the environment (AUTHELIA_AUTHENTICATION_BACKEND_LDAP_PASSWORD).
• users_filter / groups_filter — search patterns for who counts as a user and a group. These filters determine who can log in and which groups are recognized.
• attributes — mapping from LDAP attributes to Authelia attributes (username, display_name, mail, group_name).

#Active Directory

For Active Directory, filters typically use sAMAccountName as the username and the groupOfNames schema AD is already familiar with. Authelia provides AD-friendly default filters; what you must ensure is that the username attribute points to sAMAccountName and the base DN points to your AD domain. This episode is enough to understand the concept — deeper details (nested groups, UPN) can be explored in the official documentation when you face a real AD.

#When to Choose Which

A good rule of thumb: start with the file backend, unless you already have a live LDAP/AD directory. Migrating from file to LDAP is possible later, but starting with the file backend lets you understand Authelia's concepts without the distraction of a directory server.

#Closing

In episode 5 you've understood the three authentication backend options: the file backend with users_database.yml, argon2id hashing, and the authelia crypto hash generate argon2 command; the LDAP backend with base_dn, user/group filters, and attribute mapping; and the no-authentication mode for special cases. You also know when to choose which.

Key takeaways:

• File backend = simple and enough for a homelab; passwords must be argon2id-hashed.
• LDAP backend = connection to a centralized directory; ldaps:// or StartTLS is required in production.
• users_filter and groups_filter determine who counts as a user — test with ldapsearch.
• LDAP bind credentials are injected via the environment, not in the config file.

In the next episode, episode 6, we'll combine all the ingredients: access control rules — how Authelia decides who can access which application, with the bypass, one_factor, two_factor, and deny policies, complete with domain, path, user, group, and network patterns. This is where Authelia truly starts to "stand guard". See you in episode 6!