Learn Authelia - Session Management

#Introduction

In episode 6, you wrote access rules: who can access which domain and with what level of authentication. But imagine if Authelia asked for a login again for every image file a page loads. That would feel like queuing behind security guards at every hallway door. The solution is the session: log in once, identity is remembered for a period of time.

A session is the lanyard card given after login. The cookie is the physical card your browser carries, and the session storage is the reception desk where the guard verifies the card's authenticity. In this episode you'll configure that lanyard card: its name, validity, where its data is stored, and how to make it hard to forge.

#Anatomy of Session Configuration

The session section controls cookie behavior and the domains Authelia can serve. The basic configuration:

session:
  secret: "replace-with-a-long-64-character-secret"
  name: "authelia_session"
  same_site: "lax"
  inactivity: "5m"
  expiration: "1h"
  remember_me: "1M"
  cookies:
    - domain: "example.com"
      authelia_url: "https://auth.example.com"

Each field has a specific role:

• secret: the key used to encrypt session data stored in Redis. Must be strong and random, because anyone holding this secret can unpack the session contents.
• name: the cookie name used by the browser, default is authelia_session.
• inactivity: the session expires after the user is inactive for this duration. A short value like 5m closes the session automatically when you step away from your laptop.
• expiration: the maximum session age, regardless of how active the user is. This forces periodic re-authentication.
• remember_me: the session duration when the "remember me" box is checked, usually much longer than expiration.

#remember_me: Convenience vs Security

When a user checks "remember me", the cookie lasts for remember_me (for example 1M for one month) instead of the short expiration. That's convenient for personal devices, but dangerous when used on shared devices. A common policy in many organizations: enable remember_me only on networks you trust.

#Storing Sessions: Memory vs Redis

Authelia has two session storage providers:

• Memory: session data is stored inside the Authelia process. Without additional configuration, this is stateful. When Authelia restarts, all sessions are lost and every user must log in again. This provider also can't be used for more than one Authelia instance because sessions aren't shared.
• Redis: sessions are stored on a separate Redis server. Authelia becomes stateless: any instance can validate the same session, and an Authelia restart doesn't wipe sessions.

session:
  secret: "replace-with-a-long-64-character-secret"
  redis:
    host: "redis"
    port: 6379
    username: "authelia"
    password: "redis-secret"
    database_index: 0

session:
  secret: "replace-with-a-long-64-character-secret"
  name: "authelia_session"

session:
  secret: "replace-with-a-long-64-character-secret"
  name: "authelia_session"
  redis:
    host: "redis"
    port: 6379
    password: "redis-secret"

Redis is strongly recommended for production. Because session secret data is encrypted with this key, make sure the secret is strong and identical across all Authelia instances sharing the same Redis. For high availability, Authelia also supports Redis Sentinel so failover happens automatically when the primary Redis server goes down.

#Cookie Security: The Three Main Flags

The session cookie is the key that validates your identity on every request. If a cookie can be read or stolen, an attacker can impersonate you without knowing your password. Three defense mechanisms are available to a cookie:

• HttpOnly: the cookie can't be accessed by JavaScript. If an XSS attack occurs, malicious scripts can't steal the session from document.cookie. Authelia enables this automatically.
• Secure: the cookie is only sent over HTTPS, so it doesn't leak on open networks. Authelia sets this flag automatically when the service is accessed over HTTPS.
• SameSite: restricts when the cookie is sent with cross-site requests, neutralizing most CSRF attacks. The lax value (default) is a good balance between security and functionality.

Session hijacking isn't only prevented from the cookie side: with Redis as storage, you can also use Redis Sentinel, and set database_index to separate session data from other application data on the same Redis. The fewer parties that can access the session storage, the harder a session is to forge.

#Domain Scope and Multi-Domain

Cookies are only sent to domains matching their domain attribute. Authelia handles this via the cookies list where each entry defines a protected SSO domain along with its portal URL:

session:
  cookies:
    - domain: "example.com"
      authelia_url: "https://auth.example.com"
      default_redirection_url: "https://app.example.com"
    - domain: "example.org"
      authelia_url: "https://auth.example.org"
      default_redirection_url: "https://app.example.org"

A few important rules here:

• With the example.com domain, the cookie applies to all its subdomains — app.example.com, admin.example.com, and so on. This is what makes SSO across services on one main domain feel seamless.
• Two domain entries can't be suffixes of each other. The example.com and sub.example.com domains can't be registered together because they collide.
• For genuinely different root domains, the browser isolates each cookie. A single Authelia session can't be shared across different domains like example.com and example.net. For that scenario you need the OpenID Connect route, which will be covered in the identity phase in episode 17.

#Closing

Key points of this episode:

• A session is a digital lanyard: the cookie is the physical card, the storage is the reception desk.
• inactivity closes idle sessions, expiration limits the maximum age, remember_me extends it explicitly.
• Redis makes Authelia stateless, restart-tolerant, and multi-instance ready; memory is for development only.
• Cookies are protected by three flags: HttpOnly, Secure, and SameSite.
• A single main domain can serve all subdomains; different domains need separate sessions or OIDC.

Sessions are temporary: when Authelia restarts or a session expires, everything is gone. But there's data that must survive a lifetime — TOTP secrets, WebAuthn credentials, even Duo device IDs. In episode 8, you'll get to know the storage backend: the permanent data database choices, their configuration, schema migrations, and backup strategies that prevent users from losing their MFA devices.