Learn Authelia - Configuration File Structure

#Introduction

In episode 3 you ran Authelia with a minimal configuration. Now it's time to understand the brain of Authelia: configuration.yml. This is the file that determines everything — and because YAML is indentation-sensitive, a small mistake leads to wrong behavior or a server that refuses to start. In this episode we dissect every part: from server identity (theme, secret, default URL) to policies (access control, session, regulation), storage, notifications (notifier), and the user source (authentication backend). We'll also learn how to validate the configuration before running it — a skill that will save you countless times for the rest of this series.

#Anatomy of configuration.yml

The Authelia configuration file consists of the following sections, each with a clear responsibility:

#Server, Theme, and Identity

host: 0.0.0.0
port: 9091
log_level: info
 
theme: auto
jwt_secret: from-environment-variable
default_redirection_url: https://auth.example.com

• host: 0.0.0.0 makes the server accept connections from any interface (required for containers); theme: auto follows the visitor's OS preference — lightweight but professional.
• jwt_secret is used to sign verification tokens — don't hardcode it, inject it via the environment (see below). default_redirection_url is the user's "home" after login; point it to the portal or a safe main page.

#Access Control

The most important and most commonly misconfigured section. Rules are evaluated top to bottom, first match wins:

access_control:
  default_policy: deny
  rules:
    - domain: "public.example.com"
      policy: bypass
    - domain: "*.example.com"
      policy: two_factor
      subject:
        - "group:admins"

default_policy: deny ensures anything not listed is denied. The first rule allows public.example.com without login; the second rule requires two factors for the admins group on all subdomains. Episode 6 covers access control in depth.

#Session

Configures the cookie and session storage:

session:
  name: authelia_session
  domain: example.com
  expiration: 1h
  inactivity: 5m
  remember_me_duration: 1M
  redis:
    host: redis
    port: 6379
    password: from-environment-variable

The cookie is scoped to the example.com domain (so it applies to all subdomains), expires after 1 hour, and can be "remembered" for up to 1 month. inactivity: 5m forces an automatic logout after 5 minutes of inactivity — a security feature that's often underrated.

#Regulation (Brute Force Protection)

regulation:
  max_retries: 5
  find_time: 2m
  ban_time: 5m

Meaning: after 5 failed login attempts within 2 minutes, the user/IP is blocked for 5 minutes. This is the first shield against password-guessing attacks. Episode 21 covers tuning it.

#Storage and Notifier

storage:
  local:
    path: /config/db.sqlite3
 
notifier:
  filesystem:
    filename: /config/notifications.txt

Storage holds TOTP secrets and WebAuthn credentials — data that must never be lost (backup is important, episode 27). The filesystem notifier is enough for the lab; production uses SMTP.

#Authentication Backend, Identity Validation, TOTP, WebAuthn

authentication_backend:
  file:
    path: /config/users_database.yml
 
identity_validation:
  reset_password:
    jwt_secret: from-environment-variable
 
totp:
  issuer: Authelia
 
webauthn:
  display_name: Authelia

authentication_backend determines the source of user accounts (episode 5). identity_validation.reset_password.jwt_secret is used for password reset tokens — also required to be injected via the environment. totp and webauthn adjust the issuer name displayed when users scan a QR code.

#Validating the Configuration

Before restarting the stack after changing config, always validate first. Authelia provides the authelia validate-config command:

docker run --rm -v $(pwd)/config:/config authelia/authelia:latest \
  authelia validate-config --config /config/configuration.yml

authelia validate-config --config /config/configuration.yml

If there are errors, Authelia reports the line number and a description of the problem — read that before guessing. This validation doesn't need a running server, so it's safe to run anytime. Note: authelia validate-config requires all needed secrets; if they're missing, it will error before validating the file contents — this is why environment injection matters even during validation.

#Secret Management via Environment Variables

Authelia supports full configuration override through environment variables. Every key in configuration.yml has an env var equivalent: lowercase letters become underscores prefixed with AUTHELIA_. Examples:

This pattern keeps configuration.yml free of secrets — it can be safely version-controlled, while the secret values live in .env, system environment, or a secret manager (the pattern you already saw running in episode 3).

#Common Pitfalls

1. Wrong YAML indentation. A single misplaced space can change the structure. Use an editor with YAML syntax highlighting.
2. Missing required secrets. Authelia refuses to start/validate. Check the full secret list in the logs.
3. Default policy too loose or session domain inconsistent. Using default_policy: bypass "to make things easy" opens the entire lab without login; whereas a session.domain different from the portal's domain means the cookie isn't sent and the login "floats".
4. Changing config without validating. One mistake → container restart loop. Make validation a habit.

#Closing

In episode 4 you've dissected configuration.yml end to end: server identity (host, theme, jwt_secret, default_redirection_url), policies (access_control, session, regulation), storage, notifications (notifier), user source (authentication_backend), and MFA configuration (identity_validation, totp, webauthn). You've also mastered configuration validation with authelia validate-config and the secret via environment variables pattern prefixed with AUTHELIA_.

Key takeaways:

• configuration.yml is the single brain of Authelia — understand every section before changing it.
• default_policy: deny and the first match wins rule evaluation are the foundation of access control.
• Validate before restarting: authelia validate-config prevents wasted restart loops.
• Environment variables override the config file — keep secrets in .env, not in YAML.

In the next episode, episode 5, we'll cover the part that makes Authelia truly "know" its users: authentication backends — the file backend with users_database.yml and argon2id-hashed passwords for homelabs, plus the LDAP backend for organizations with OpenLDAP or Active Directory. See you in episode 5!