Learn Authelia - Architecture & Core Concepts

#Introduction

After episode 1, where we understood why Authelia is needed — one entrance for many applications — in this episode we dissect how Authelia works behind the scenes. This is the most important episode to understand before touching any configuration: without the architecture, all the configuration.yml syntax is just memorization that's easy to misuse.

We'll map out the architecture components, understand the core concepts (portal, access control, 1FA vs 2FA, session), then follow the journey of a single HTTP request from the browser all the way back carrying a session cookie. Just as a pilot must understand how the wings work before flying, engineers who understand Authelia's architecture will debug problems in the following episodes much faster.

#Architecture Components

Authelia never runs alone. It's a single point of coordination among five other components. Let's break them down one by one.

#The Authelia Server

The heart is the Authelia binary written in Go. It serves two purposes: the verification endpoint (which the reverse proxy calls to evaluate every request) and the login portal (the interface where users sign in). By default it listens on port 9091. The server is "stateless" as far as sessions go — all sessions are stored in Redis, so it will be easy to scale horizontally later in the high availability episode.

#Configuration File

All of Authelia's behavior is determined by a single file: configuration.yml. From here Authelia knows where users are stored, where sessions are stored, how to send notifications, and what access rules apply. We'll dissect this file thoroughly in episode 4.

#Session Storage

Login state (sessions) is stored centrally — usually in Redis. Why not inside Authelia itself? Because with Redis, sessions can be shared across multiple Authelia instances, and sessions can be revoked centrally. For development, Authelia also supports in-memory sessions, but Redis is the production recommendation. Episode 7 covers sessions in full.

#User Database (Authentication Backend)

The source of truth for user accounts. Authelia doesn't force a particular format — it supports a YAML file (users_database.yml) for small scale, as well as LDAP and Active Directory for organizations. This is called the authentication backend, and episode 5 will cover all three in depth.

#Storage Backend

Different from the user database, the storage backend stores data that Authelia itself generates: TOTP secrets, WebAuthn credentials, identity verification tokens, and OIDC consent records. The options: local SQLite (default, simplest), PostgreSQL, or MySQL/MariaDB. Episode 8 covers this.

#Notifier

Authelia needs to send emails — for example verification codes for password resets or device registration confirmations. Two options: SMTP for production, and filesystem (writing "emails" to a local file) for the lab. Episode 12 covers SMTP configuration.

#Core Concepts

Some terms will keep appearing throughout this entire series. Understand them now so you don't get lost later:

• Portal — Authelia's login page (auth.example.com). This is the only entrance for all protected applications.
• Protected domain — a protected subdomain, for example grafana.example.com. All requests to this domain must pass Authelia verification.
• Access control rules — a list of rules that determine who can access what. Rules are evaluated in order, first match wins, with the bypass, one_factor, two_factor, or deny policies.
• 1FA vs 2FA — one-factor means password only; two-factor means password + a second method (TOTP, WebAuthn, or Duo). Authelia doesn't require all applications to use 2FA — you decide per rule.
• Session — the "logged in" state stored in a cookie and Redis. Controls how long a session lasts, when it expires, and the "remember me" feature.
• OIDC provider — Authelia can also act as an Identity Provider for modern applications that support OpenID Connect (covered in phase 5).

#End-to-End Authentication Flow

This is the "everything comes together" moment. Follow the journey of a single request:

1. The user types https://grafana.example.com in the browser.
2. The reverse proxy (for example NGINX) receives the request and asks Authelia: "Is this user authenticated?" — via the verification endpoint.
3. Authelia checks the session cookie in the request.
4. No valid session → Authelia answers "not authenticated" and provides the login portal location.
5. The proxy redirects the user's browser to the portal at https://auth.example.com.
6. The user logs in with username + password at the portal.
7. If the resource requires two factors, Authelia asks for the second method (TOTP/WebAuthn/Duo).
8. Authelia creates a session, stores it in Redis, and sets the session cookie in the browser.
9. The browser is redirected back to https://grafana.example.com — now carrying the session cookie.
10. The proxy asks Authelia again; this time the session is valid → Authelia answers "allowed" along with the user's identity.
11. The proxy forwards the request to Grafana, including the identity headers (Remote-User, Remote-Groups).
12. Grafana opens the page — for a user it now recognizes.

Browser                    Proxy (NGINX)          Authelia              Redis
   |  1. GET / (no cookie)      |                      |                   |
   |--------------------------->|  2. verify?          |                   |
   |                            |--------------------->|  3. check session |
   |                            |                      |------------------>|
   |                            |                      |  4. none          |
   |                            |<---------------------|<------------------|
   |  5. redirect to portal     |                      |                   |
   |<---------------------------|                      |                   |
   |  6. POST username+pass     |                      |                   |
   |--------------------------------------------------->|  7. validate user|
   |                            |                      |  8. create session|
   |                            |                      |------------------>|
   |  9. set cookie + redirect  |                      |                   |
   |<---------------------------|                      |                   |
   | 10. GET / (with cookie)    |                      |                   |
   |--------------------------->| 11. verify?          |                   |
   |                            |--------------------->| 12. session valid |
   |                            |                      |------------------>|
   |                            |<---------------------|<------------------|
   | 13. GET / + Remote-User    |                      |                   |
   |<---------------------------| 14. Grafana response |                   |

#The Security Model

Authelia is built on the principle of defense in depth — multiple layers of defense, not a single fence:

• Rule-based access control — access is denied by default (deny), only opened through explicit rules.
• Multi-factor authentication — a second layer for sensitive resources.
• Brute force protection (regulation) — failed login attempts are rate limited by IP and user.
• Session security — cookies are encrypted, locked to the domain, and can have a limited lifetime.
• Password policies — Authelia doesn't enforce "strong" passwords at the server level for file backends, but relies on argon2id hashing that resists offline attacks (details in episode 5).

#Closing

In episode 2 you've mapped Authelia's architecture: the Go server as coordinator, configuration.yml as the brain, Redis for sessions, the authentication backend (file/LDAP/AD) for user accounts, the storage backend (SQLite/PostgreSQL/MySQL) for MFA data, and the notifier for emails. You've also followed the complete journey of a single request: from browser, to proxy, to Authelia verification, to portal, back with a session cookie, until the application receives identity headers.

Key takeaways:

• Authelia is the decision maker; the reverse proxy is the door; applications are rooms that never see credentials.
• Sessions in Redis enable horizontal scaling and centralized revocation.
• Access control is evaluated in order, first match wins — and the safe default is deny.
• 1FA vs 2FA is a per-rule choice, not a single global switch.
• Applications recognize users via identity headers, not via Authelia sessions.

In the next episode, episode 3, we'll start taking action: installing Authelia with Docker Compose — assembling the Authelia + Redis + database stack, creating a minimal configuration file, managing secrets via a .env file, and verifying your first Authelia portal. See you in episode 3!