How to Deploy Authelia – Open-Source Authentication and Authorization Gateway

Authelia is an open-source authentication and authorization server that provides two-factor authentication (2FA) and single sign-on (SSO) for web applications through a login portal. It acts as a companion for reverse proxies like Traefik, NGINX, and Caddy by allowing, denying, or redirecting requests based on access control policies. With a container size under 20 megabytes and memory usage typically under 30 megabytes, Authelia is one of the most lightweight authentication solutions available.

This article explains how to deploy Authelia on a Linux server using Docker Compose with Traefik as the reverse proxy. It covers directory setup, Authelia configuration, automatic HTTPS with Let's Encrypt, and protecting a sample web application with authentication policies.

Prerequisites

Before you begin, you need to:

• Have access to a Linux-based server (with at least 2 CPU cores and 4 GB of RAM) as a non-root user with sudo privileges.
• Install Docker and Docker Compose.
• Configure DNS A records pointing to your server's IP address for the following subdomains: auth.example.com (Authelia portal), app.example.com (protected application), and traefik.example.com (Traefik dashboard).

Set Up the Directory Structure, Configuration, and Environment Variables

Authelia requires a project directory that holds its configuration file, user database, and secrets for JSON Web Token (JWT) management, session handling, and storage encryption.

1. Create the project directory with subdirectories for Authelia configuration, secrets, and logs.

   CONSOLE

   Copy

   $ mkdir -p ~/authelia/{config,secrets,logs}

   Explain Code

   Powered by Vultr AgentBeta
   • config: Holds the main configuration file (configuration.yml) and the user database (users.yml).
   • secrets: Stores sensitive values such as JWT, session, and storage encryption secrets.
   • logs: Stores Authelia application logs.

2. Navigate to the project directory.

   CONSOLE

   Copy

   $ cd ~/authelia

   Explain Code

   Powered by Vultr AgentBeta

3. Create the environment file.

   CONSOLE

   Copy

   $ nano .env

   Explain Code

   Powered by Vultr AgentBeta

4. Add the following configuration:

   INI

   Copy

   DOMAIN=example.com
   LETSENCRYPT_EMAIL=admin@example.com

   Explain Code

   Powered by Vultr AgentBeta

   Replace:

   • example.com with your registered domain (the parent domain for all subdomains).
   • admin@example.com with your email address for Let's Encrypt certificate notifications.

   Save and close the file.

5. Set ownership on the secrets directory and generate the Authelia secrets. The Authelia container runs as UID 8000 and needs write access to the secrets directory.

   CONSOLE

   Copy

   $ sudo chown 8000:8000 ./secrets
   $ sudo chmod 0700 ./secrets
   $ docker run --rm -u 8000:8000 -v ./secrets:/secrets docker.io/authelia/authelia:4.39 sh -c "cd /secrets && authelia crypto rand --length 64 session_secret.txt storage_encryption_key.txt jwt_secret.txt"

   Explain Code

   Powered by Vultr AgentBeta
   • chown 8000:8000: Sets ownership to the Authelia container user.
   • chmod 0700: Restricts access to the secrets directory to the owner only.
   • authelia crypto rand: Generates cryptographically secure random strings of 64 characters for each secret file.

6. Create the Authelia configuration file.

   CONSOLE

   Copy

   $ nano config/configuration.yml

   Explain Code

   Powered by Vultr AgentBeta

7. Add the following configuration. Replace all instances of example.com with your actual domain.

   YAML

   Copy

   server:
     address: 'tcp4://:9091'
   
   log:
     level: 'info'
     file_path: '/var/log/authelia/authelia.log'
     keep_stdout: true
   
   identity_validation:
     elevated_session:
       require_second_factor: true
     reset_password:
       jwt_lifespan: '5 minutes'
       jwt_secret: {{ secret "/secrets/jwt_secret.txt" | mindent 0 "|" | msquote }}
   
   totp:
     disable: false
     issuer: 'example.com'
     period: 30
     skew: 1
   
   authentication_backend:
     file:
       path: '/config/users.yml'
       password:
         algorithm: 'argon2'
         argon2:
           variant: 'argon2id'
           iterations: 3
           memory: 65535
           parallelism: 4
           key_length: 32
           salt_length: 16
   
   access_control:
     default_policy: 'deny'
     rules:
       - domain: 'app.example.com'
         policy: 'two_factor'
       - domain: 'traefik.example.com'
         policy: 'one_factor'
   
   session:
     name: 'authelia_session'
     secret: {{ secret "/secrets/session_secret.txt" | mindent 0 "|" | msquote }}
     cookies:
       - domain: 'example.com'
         authelia_url: 'https://auth.example.com'
   
   regulation:
     max_retries: 4
     find_time: 120
     ban_time: 300
   
   storage:
     encryption_key: {{ secret "/secrets/storage_encryption_key.txt" | mindent 0 "|" | msquote }}
     local:
       path: '/config/db.sqlite3'
   
   notifier:
     disable_startup_check: false
     filesystem:
       filename: '/config/notification.txt'

   Explain Code

   Powered by Vultr AgentBeta

   Save and close the file.

   • server: Configures Authelia to listen on port 9091.
   • authentication_backend: Uses a file-based user database with Argon2id password hashing.
   • access_control: Denies all requests by default. The app.example.com subdomain requires 2FA, and traefik.example.com requires single-factor authentication.
   • session.cookies: Scopes session cookies to the parent domain example.com, enabling SSO across all subdomains.
   • storage: Uses a local SQLite database for simplicity.
   • notifier: Writes notification emails such as 2FA setup links to a local file. Replace this with Simple Mail Transfer Protocol (SMTP) configuration for production use.

8. Generate a secure password hash. Replace your-secure-password with your desired password.

   CONSOLE

   Copy

   $ docker run --rm authelia/authelia:4.39 authelia crypto hash generate argon2 --password 'your-secure-password'

   Explain Code

   Powered by Vultr AgentBeta

   Copy the output hash for use in the next step.

9. Create the user database file.

   CONSOLE

   Copy

   $ nano config/users.yml

   Explain Code

   Powered by Vultr AgentBeta

10. Add the following configuration:

    YAML

    Copy

    users:
      authuser:
        displayname: 'Auth User'
        password: '$argon2id$v=19$m=65536,t=3,p=4$BpLnfgDsc2WD8F2q$Zis.ixdg9s/UOJYrs56b5QEZFiZECu0qZVNsIYxBaNJ7ucIL.nlxVCT5tqh8KHG8X4tlwCFm5r6NTOZZ5qRFN/'
        email: 'authuser@example.com'
        groups:
          - 'admin'

    Explain Code

    Powered by Vultr AgentBeta

    Replace:

    • authuser@example.com with your email address.
    • The password value with your generated hash.

    Save and close the file.

Deploy with Docker Compose

The Docker Compose manifest defines Traefik as the reverse proxy, Authelia as the authentication gateway, and a sample whoami application to demonstrate authentication enforcement. This configuration is based on the official Authelia Docker examples.

1. Create the Docker Compose manifest.

   CONSOLE

   Copy

   $ nano docker-compose.yaml

   Explain Code

   Powered by Vultr AgentBeta

2. Add the following configuration:

   YAML

   Copy

   services:
     traefik:
       image: traefik:v3.6
       container_name: traefik
       depends_on:
         - authelia
       command:
         - "--api.dashboard=true"
         - "--providers.docker=true"
         - "--providers.docker.exposedbydefault=false"
         - "--entrypoints.web.address=:80"
         - "--entrypoints.websecure.address=:443"
         - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
         - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
         - "--certificatesresolvers.letsencrypt.acme.tlschallenge=true"
         - "--certificatesresolvers.letsencrypt.acme.email=${LETSENCRYPT_EMAIL}"
         - "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json"
       ports:
         - "80:80"
         - "443:443"
       volumes:
         - "./letsencrypt:/letsencrypt"
         - "/var/run/docker.sock:/var/run/docker.sock:ro"
       labels:
         - "traefik.enable=true"
         - "traefik.http.routers.dashboard.rule=Host(`traefik.${DOMAIN}`)"
         - "traefik.http.routers.dashboard.entrypoints=websecure"
         - "traefik.http.routers.dashboard.tls.certresolver=letsencrypt"
         - "traefik.http.routers.dashboard.service=api@internal"
         - "traefik.http.routers.dashboard.middlewares=authelia@docker"
       restart: unless-stopped
   
     authelia:
       image: authelia/authelia:4.39
       container_name: authelia
       volumes:
         - "./secrets:/secrets:ro"
         - "./config:/config"
         - "./logs:/var/log/authelia"
       environment:
         TZ: "UTC"
         X_AUTHELIA_CONFIG_FILTERS: "template"
       labels:
         - "traefik.enable=true"
         - "traefik.http.routers.authelia.rule=Host(`auth.${DOMAIN}`)"
         - "traefik.http.routers.authelia.entrypoints=websecure"
         - "traefik.http.routers.authelia.tls.certresolver=letsencrypt"
         - "traefik.http.middlewares.authelia.forwardAuth.address=http://authelia:9091/api/authz/forward-auth"
         - "traefik.http.middlewares.authelia.forwardAuth.trustForwardHeader=true"
         - "traefik.http.middlewares.authelia.forwardAuth.authResponseHeaders=Remote-User,Remote-Groups,Remote-Name,Remote-Email"
       restart: unless-stopped
   
     whoami:
       image: traefik/whoami
       container_name: whoami
       depends_on:
         - authelia
       labels:
         - "traefik.enable=true"
         - "traefik.http.routers.whoami.rule=Host(`app.${DOMAIN}`)"
         - "traefik.http.routers.whoami.entrypoints=websecure"
         - "traefik.http.routers.whoami.tls.certresolver=letsencrypt"
         - "traefik.http.routers.whoami.middlewares=authelia@docker"
       restart: unless-stopped

   Explain Code

   Powered by Vultr AgentBeta

   Save and close the file.

   In the above manifest:

   • services: Launches three containers managed by Docker Compose:
     • traefik: Functions as the reverse proxy and TLS termination point with automatic Let's Encrypt certificates.
     • authelia: Runs the authentication gateway on port 9091.
     • whoami: A lightweight service that displays HTTP request headers for testing authentication.
   • command (Traefik): Configures Traefik's core behavior including Docker discovery, HTTP/HTTPS entry points, automatic HTTP-to-HTTPS redirection, and Let's Encrypt certificate generation.
   • environment (Authelia): The X_AUTHELIA_CONFIG_FILTERS: "template" setting enables the template filter that loads secrets from files.
   • labels (Authelia): The forwardAuth labels instruct Traefik to check every request against Authelia before forwarding it to backend services.
   • labels (whoami): The authelia@docker middleware attaches authentication to the whoami service.
   • volumes: The letsencrypt directory stores TLS certificates persistently. The Docker socket enables Traefik to discover and route to containers automatically.
   • restart: unless-stopped: Ensures containers recover automatically after failures or restarts.

3. Launch the containers.

   CONSOLE

   Copy

   $ docker compose up -d

   Explain Code

   Powered by Vultr AgentBeta

4. Verify all three services are running.

   CONSOLE

   Copy

   $ docker compose ps

   Explain Code

   Powered by Vultr AgentBeta

   The output displays three running containers: Traefik, Authelia, and whoami with Traefik listening on ports 80 and 443.

5. Check the service logs for any errors.

   CONSOLE

   Copy

   $ docker compose logs

   Explain Code

   Powered by Vultr AgentBeta

   For more information on managing a Docker Compose stack, see the How to Use Docker Compose article.

Access and Configure Authelia

Authelia serves a web portal for user authentication. The first login requires setting up a Time-based One-Time Password (TOTP) device for 2FA using the filesystem notifier to retrieve verification codes.

1. Open a web browser and navigate to https://auth.example.com, replacing example.com with your configured domain.

   

2. Sign in with the default credentials:

   • Username: authuser
   • Password: The password you set when generating the hash earlier.

3. After a successful login, Authelia displays the portal page with a prompt to register your first 2FA device. Click Register device to begin the TOTP setup process.

4. Authelia displays an Identity Verification dialog requesting a One-Time Code. Since the notifier uses a filesystem backend, retrieve the code from the server.

   CONSOLE

   Copy

   $ docker compose exec authelia cat /config/notification.txt

   Explain Code

   Powered by Vultr AgentBeta

5. After verification, Authelia displays a QR code. Scan it with a TOTP authenticator app such as Google Authenticator, Authy, or Microsoft Authenticator. Enter the 6-digit code from the app to complete the registration.

Test Authentication and Single Sign-On

The whoami container displays HTTP request headers and connection details, allowing you to verify that Authelia correctly enforces authentication and injects identity headers.

1. Open a web browser and navigate to https://app.example.com, replacing example.com with your configured domain.

2. Authelia redirects to the login portal at https://auth.example.com. Enter your username and password. Since app.example.com uses a two_factor policy, Authelia prompts for a TOTP code after the password step. Enter the 6-digit code from your authenticator app to gain access.

   

3. After successful authentication, the browser displays the whoami output. Verify that Authelia injects identity headers into the proxied request by looking for the following headers:

   Remote-User: authuser
   Remote-Name: Auth User
   Remote-Email: authuser@example.com
   Remote-Groups: admin

   These headers allow backend applications to identify the authenticated user without implementing their own authentication logic.

4. Test SSO functionality by opening a new tab and navigating to https://traefik.example.com, replacing example.com with your configured domain. Since the session cookie scopes to the parent domain, Authelia recognizes your existing session. The Traefik dashboard requires only one_factor authentication, so Authelia grants access immediately without prompting for credentials again.

   

5. To protect additional web applications, add the Authelia middleware label to any new service in your docker-compose.yaml:

   YAML

   Copy

   labels:
     - "traefik.enable=true"
     - "traefik.http.routers.<service-name>.rule=Host(`newapp.${DOMAIN}`)"
     - "traefik.http.routers.<service-name>.entrypoints=websecure"
     - "traefik.http.routers.<service-name>.tls.certresolver=letsencrypt"
     - "traefik.http.routers.<service-name>.middlewares=authelia@docker"

   Explain Code

   Powered by Vultr AgentBeta

   Then add a corresponding rule in the access_control section of config/configuration.yml:

   YAML

   Copy

   - domain: 'newapp.example.com'
     policy: 'one_factor'

   Explain Code

   Powered by Vultr AgentBeta

   Run docker compose up -d to apply the changes.

Conclusion

You have successfully deployed Authelia with Traefik as the reverse proxy on a Linux server using Docker Compose. The setup provides centralized 2FA and SSO for web applications behind the proxy. For more information on extending this configuration with SMTP notifications, Lightweight Directory Access Protocol (LDAP) user backends, or OpenID Connect 1.0, visit the official Authelia documentation.