EN

Applications

Protect Your Services with Authelia and Caddy

Deploy Authelia on Debian or Ubuntu with Docker and Caddy: authentication portal, two-factor authentication, separate secrets, access rules, updates and backups.

9 min read, updated on 18 November 2026

On this page

Your values

Enter them once and the commands in this guide update.

This guide explains how to place Authelia in front of your web applications. For every request, the Caddy reverse proxy asks Authelia whether the visitor may pass. If the visitor is not identified, they are sent to a sign-in portal that requires a password and a second factor.

By the end of the guide, https://app.your-domain.com is reachable only after two-factor authentication on https://auth.your-domain.com. The secrets are kept separate from the configuration, and you know how to update and back up the installation.

Order a Server

This guide applies to servers that you administer yourself:

Prerequisites

  • A server running Debian 12 or 13, or Ubuntu 22.04 or 24.04
  • SSH access with a user that has sudo
  • Docker Engine and Docker Compose, installed with the guide Install Docker Engine and Docker Compose
  • Caddy, installed with the guide Caddy as a Reverse Proxy with Automatic HTTPS
  • A domain whose DNS zone you manage, with auth.your-domain.com and app.your-domain.com pointing to YOUR_SERVER_IP
  • An application to protect, which listens only locally, here on 127.0.0.1:3000
  • An SMTP account to send verification codes and password resets

Ports Used

Port Direction Purpose To open
80/tcp Inbound Certificate validation and redirect to HTTPS Yes
443/tcp Inbound Authelia portal and protected applications Yes
443/udp Inbound HTTP/3 Recommended
9091/tcp Local Authelia, on 127.0.0.1 only No
3000/tcp Local Example application No

Authelia also trusts the X-Forwarded-* headers that the proxy sends it. Its port must therefore never be reachable from the Internet.

Step 1: Create the Folders and the Secrets

Authelia needs three secrets: the signing key for reset links, the session key and the database encryption key. Each one is placed in its own file, outside the configuration.

Terminal
sudo mkdir -p /opt/authelia/config /opt/authelia/secrets
for name in JWT_SECRET SESSION_SECRET STORAGE_ENCRYPTION_KEY; do
  openssl rand -hex 64 | sudo tee "/opt/authelia/secrets/$name" > /dev/null
done
sudo nano /opt/authelia/secrets/SMTP_PASSWORD

In the last file, enter the password of your SMTP account, alone on the first line.

Step 2: Create the First User

Compute the hash of your password. The command asks for it twice:

Terminal
sudo docker run --rm -it authelia/authelia:4.39.28 authelia crypto hash generate argon2

It prints a line starting with Digest:. Create the users file:

Terminal
sudo nano /opt/authelia/config/users.yml

Copy only the value that starts with $argon2id$, between single quotes:

YAML
users:
  YOUR_USER:
    disabled: false
    displayname: 'Admin'
    password: '$argon2id$v=19$m=65536,t=3,p=4$...'
    email: 'admin@your-domain.com'
    groups:
      - 'admins'

This email address receives the verification codes: it must be valid.

Step 3: Write the Configuration

Terminal
sudo nano /opt/authelia/config/configuration.yml
YAML
server:
  address: 'tcp://:9091/'

log:
  level: 'info'

totp:
  issuer: 'auth.your-domain.com'

authentication_backend:
  file:
    path: '/config/users.yml'
    password:
      algorithm: 'argon2'

session:
  cookies:
    - domain: 'your-domain.com'
      authelia_url: 'https://auth.your-domain.com'
      default_redirection_url: 'https://app.your-domain.com'

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

regulation:
  modes:
    - 'user'
    - 'ip'
  max_retries: 3
  find_time: '2 minutes'
  ban_time: '10 minutes'

notifier:
  smtp:
    address: 'submission://smtp.your-domain.com:587'
    username: 'authelia@your-domain.com'
    sender: 'Authelia <authelia@your-domain.com>'

access_control:
  default_policy: 'deny'
  rules:
    - domain: 'app.your-domain.com'
      policy: 'two_factor'
Section Purpose
authentication_backend Accounts read from users.yml, passwords hashed with Argon2id
session.cookies Protected domain and portal address, which must use HTTPS
storage SQLite database, suited to a single Authelia instance
regulation Temporary lockout after three failures within two minutes
notifier Sends emails. submission:// uses STARTTLS, submissions:// uses direct TLS
access_control Everything is denied, except what a rule allows

Step 4: Start Authelia

Terminal
sudo nano /opt/authelia/compose.yaml
YAML
services:
  authelia:
    image: authelia/authelia:4.39.28
    restart: unless-stopped
    user: "8091:8091"
    environment:
      TZ: "Europe/Paris"
      AUTHELIA_IDENTITY_VALIDATION_RESET_PASSWORD_JWT_SECRET_FILE: /secrets/JWT_SECRET
      AUTHELIA_SESSION_SECRET_FILE: /secrets/SESSION_SECRET
      AUTHELIA_STORAGE_ENCRYPTION_KEY_FILE: /secrets/STORAGE_ENCRYPTION_KEY
      AUTHELIA_NOTIFIER_SMTP_PASSWORD_FILE: /secrets/SMTP_PASSWORD
    volumes:
      - ./config:/config
      - ./secrets:/secrets:ro
    ports:
      - "127.0.0.1:9091:9091"

The container runs as an unprivileged user. Give it access to its files, and nobody else:

Terminal
sudo chown -R 8091:8091 /opt/authelia/config /opt/authelia/secrets
sudo chmod 700 /opt/authelia/config /opt/authelia/secrets
sudo find /opt/authelia/config /opt/authelia/secrets -type f -exec chmod 600 {} +

Validate the configuration, then start the service:

Terminal
cd /opt/authelia
sudo docker compose run --rm authelia authelia config validate --config /config/configuration.yml
sudo docker compose up -d
sudo docker compose logs --tail=30 authelia
curl -fsS http://127.0.0.1:9091/api/health

The validation must print Configuration parsed and loaded successfully without errors. The logs must contain Listening for non-TLS connections, and the last command must return {"status":"OK"}.

Traffic between Caddy and Authelia stays on the server's loopback interface. Visitors, for their part, reach the portal only over HTTPS.

Step 5: Configure Caddy

If you use UFW, allow the web ports:

Terminal
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udp

Add these two sites to /etc/caddy/Caddyfile, or to a file in /etc/caddy/sites/:

caddyfile
auth.your-domain.com {
	reverse_proxy 127.0.0.1:9091
}

app.your-domain.com {
	forward_auth 127.0.0.1:9091 {
		uri /api/authz/forward-auth
		copy_headers Remote-User Remote-Groups Remote-Email Remote-Name
	}

	reverse_proxy 127.0.0.1:3000
}

forward_auth queries Authelia before every request. If access is granted, Caddy copies the user's identity into the Remote-* headers, then forwards the request to the application. Otherwise, it returns Authelia's response, usually a redirect to the portal.

Validate and apply:

Terminal
sudo caddy fmt --overwrite /etc/caddy/Caddyfile
sudo -u caddy caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
sudo systemctl reload caddy

Step 6: Register the Second Factor

  1. Open https://app.your-domain.com in a private browsing window. You land on the portal.
  2. Sign in with YOUR_USER and the password you chose in step 2.
  3. Click Register device.
  4. Enter the one-time code received by email to confirm your identity.
  5. Add a One-Time Password with your TOTP app, or a WebAuthn Security Key.
  6. Confirm the second factor: you are redirected to the application.

You can add other devices from the portal's Settings. If possible, register at least two methods, so that you do not depend on a single device.

Check the Result

Terminal
curl -si https://app.your-domain.com | grep -iE '^(HTTP|location)'
sudo ss -ltnp | grep -E ':(3000|9091) '

The first command must return a 302 code and an address https://auth.your-domain.com/ with an rd parameter. The second must show 127.0.0.1 only.

From your computer, http://YOUR_SERVER_IP:3000 and http://YOUR_SERVER_IP:9091 must not respond. Finally, run these checks in a private window:

  • the password alone does not give access to the application;
  • a wrong TOTP code is rejected;
  • after signing out of the portal, the application asks for authentication again.

Repeat these tests after every change to the proxy or to the access rules.

Add Services and Refine the Rules

To protect another service, add a Caddy site with the same forward_auth block, then an Authelia rule. Rules are read in order and the first one that matches applies.

YAML
access_control:
  default_policy: 'deny'
  rules:
    - domain: 'status.your-domain.com'
      resources:
        - '^/api/health$'
      policy: 'bypass'
    - domain: 'admin.your-domain.com'
      subject:
        - 'group:admins'
      policy: 'two_factor'
    - domain: 'app.your-domain.com'
      policy: 'two_factor'
Policy Effect
deny Access denied
bypass No authentication: reserve it for genuinely public paths
one_factor Password required
two_factor Password and second factor required

All services must be under the domain declared in session.cookies. To add a user, complete users.yml. After any change to the configuration or the users, restart Authelia:

Terminal
cd /opt/authelia
sudo docker compose restart authelia

Sessions are kept in memory: this restart signs everyone out.

Update Authelia

Read the release notes, back up, then replace the version number in compose.yaml:

Terminal
cd /opt/authelia
sudo nano compose.yaml
sudo docker compose pull
sudo docker compose run --rm authelia authelia config validate --config /config/configuration.yml
sudo docker compose up -d
sudo docker compose logs --tail=30 authelia

At startup, Authelia automatically migrates its database to the schema of the new version. The backup you made beforehand is therefore your way back. Then repeat the checks in the verification section.

Back Up and Restore

The /opt/authelia folder contains the whole state of the installation: configuration, users, SQLite database and secrets. Briefly stop the service to get a consistent copy:

Terminal
cd /opt/authelia
sudo docker compose stop authelia
sudo tar -czpf "/root/authelia-$(date +%F).tar.gz" -C /opt authelia
sudo docker compose start authelia
sudo chmod 600 "/root/authelia-$(date +%F).tar.gz"

This archive contains your secrets and the password hashes. Copy it off the server, to an encrypted location.

To check that it is usable without touching the running instance, replace the archive name, then verify the encryption key on the copy:

Terminal
sudo install -d -m 700 /root/authelia-test
sudo tar -xzpf /root/authelia-2026-11-18.tar.gz -C /root/authelia-test
cd /root/authelia-test/authelia
sudo docker compose -p authelia-test run --rm authelia authelia storage encryption check --verbose --config /config/configuration.yml
sudo docker compose -p authelia-test down
cd /
sudo rm -rf /root/authelia-test

The expected result is Storage Encryption Key Validation: SUCCESS.

To restore, on a server where Docker and Caddy are in place:

Terminal
cd /opt/authelia
sudo docker compose down
cd /
sudo mv /opt/authelia "/opt/authelia.old-$(date +%F)"
sudo tar -xzpf /root/authelia-2026-11-18.tar.gz -C /opt
cd /opt/authelia
sudo docker compose up -d

Troubleshooting

Always start with the logs:

Terminal
cd /opt/authelia
sudo docker compose logs --tail=100 authelia

secrets: error loading secret path /secrets/...

The indicated file is missing or unreadable. Check its name, then repeat the chown and chmod commands from step 4.

notifier: please ensure only one of the 'smtp' or 'filesystem' notifier is configured

You are using filesystem while AUTHELIA_NOTIFIER_SMTP_PASSWORD_FILE is still present in compose.yaml. Remove that line, then run sudo docker compose up -d again.

One or more providers had fatal failures performing startup checks

A required service failed at startup. Most often, Authelia cannot reach or use the SMTP server. The preceding error lines give the cause: address, port, credentials or blocked outbound port.

the configured encryption key does not appear to be valid for this database

STORAGE_ENCRYPTION_KEY does not match the one used to create the database. Put the right key back from your backup. To change it deliberately, use the authelia storage encryption change-key command.

the system clock is not synchronized accurately enough with the configured NTP server

The server's clock is drifting, which would make TOTP codes invalid. Check the synchronization:

Terminal
timedatectl status

Target URL does not appear to have a relevant session cookies configuration

The application's domain is not covered by session.cookies. Check domain in configuration.yml and the name used in the Caddyfile.

Target URL ... has an insecure scheme

The request arrives over HTTP. All protected applications must be served over HTTPS. Check that the Caddy site uses a public domain name, without an http:// prefix.

Access to '...' is forbidden to user '...'

The user is signed in, but no rule allows them. Check the order of the rules, the domain and the groups in users.yml.

The Password Is Rejected Even Though It Is Correct

After several failures, the account or the IP address is blocked for ban_time. Wait for the delay to end, or lift the block on the account:

Terminal
cd /opt/authelia
sudo docker compose exec authelia authelia storage bans user revoke YOUR_USER --config /config/configuration.yml

For an IP address, use authelia storage bans ip revoke YOUR_IP.

502 Error in the Browser

Caddy cannot reach Authelia or the application. Test both locally:

Terminal
curl -fsS http://127.0.0.1:9091/api/health
curl -I http://127.0.0.1:3000

References