Why Authelia?

Adding login pages and 2FA to every self-hosted app is tedious. Authelia centralizes it:

  • Single login portal for all your apps behind a reverse proxy.
  • TOTP, WebAuthn, and Duo Push 2FA methods.
  • Per-app policies — bypass, one-factor, or two-factor per domain/path.
  • Lightweight — ~30 MB Docker image, minimal RAM usage.

Prerequisites

  • Docker and docker-compose.
  • A reverse proxy (Nginx, Traefik, Caddy, or HAProxy).
  • A domain with wildcard DNS (e.g., *.home.example.com).
  • SMTP credentials for email-based password resets.

Step 1: Docker Compose Setup

# docker-compose.yml
version: "3"
services:
  authelia:
    image: authelia/authelia:latest
    container_name: authelia
    volumes:
      - ./authelia:/config
    ports:
      - "9091:9091"
    environment:
      TZ: America/Mexico_City
    restart: always

Step 2: Configuration (configuration.yml)

# authelia/configuration.yml
server:
  address: "tcp://0.0.0.0:9091"

session:
  name: authelia_session
  secret: a-very-long-random-secret
  cookies:
    - domain: home.example.com
      authelia_url: https://auth.home.example.com

storage:
  local:
    path: /config/db.sqlite3

notifier:
  smtp:
    host: smtp.gmail.com
    port: 587
    username: your@gmail.com
    password: app-password

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

access_control:
  default_policy: deny
  rules:
    # Public services — no auth needed
    - domain: public.home.example.com
      policy: bypass

    # Internal tools — password only
    - domain: "*.home.example.com"
      policy: one_factor

    # Sensitive services — require 2FA
    - domain:
        - vault.home.example.com
        - admin.home.example.com
      policy: two_factor

Step 3: Nginx Integration

server {
    server_name app.home.example.com;

    location /authelia {
        internal;
        proxy_pass http://authelia:9091/api/authz/auth-request;
        proxy_set_header X-Original-URL $scheme://$http_host$request_uri;
    }

    location / {
        auth_request /authelia;
        auth_request_set $user $upstream_http_remote_user;
        proxy_set_header Remote-User $user;
        proxy_pass http://your-app:8080;
    }
}

Step 4: User Database

# authelia/users_database.yml
users:
  admin:
    displayname: "Admin User"
    password: "$argon2id$v=19$m=65536,t=3,p=4$..."  # Use authelia hash-password
    email: admin@example.com
    groups:
      - admins

Generate password hashes: docker run authelia/authelia:latest authelia crypto hash generate argon2

Access Control Policy Reference

PolicyDescription
bypassNo authentication needed (public)
one_factorUsername + password only
two_factorUsername + password + TOTP/WebAuthn/Duo
denyBlock access entirely

Troubleshooting

ProblemSolution
Redirect loop after loginVerify the authelia_url in session cookies matches your Authelia domain exactly
2FA setup page not loadingEnsure SMTP notifier is configured — Authelia sends a registration link via email
”401 Unauthorized” on bypass rulesCheck rule order — rules are evaluated top to bottom, first match wins
Session lost between subdomainsSet the cookie domain to the parent domain (e.g., home.example.com, not app.home.example.com)
Password hash rejectedUse authelia crypto hash generate argon2 to create compatible hashes

Summary

  • Authelia provides centralized SSO + 2FA for all reverse-proxied apps.
  • Access control rules let you customize security per domain (bypass, 1FA, 2FA).
  • Integrates with Nginx, Traefik, Caddy, and HAProxy via auth subrequests.
  • Store users in a local file or connect to LDAP/Active Directory.