Protéger ses services avec Authelia et Caddy
Déployez Authelia sur Debian ou Ubuntu avec Docker et Caddy : portail d'authentification, double authentification, secrets séparés, règles d'accès, mises à jour et sauvegardes.
Sur cette page
Vos valeurs
Renseignez-les une fois, les commandes du guide se mettent à jour.
Ce guide vous explique comment placer Authelia devant vos applications web. Le reverse proxy Caddy demande à Authelia, pour chaque requête, si le visiteur peut passer. S’il n’est pas identifié, il est envoyé vers un portail de connexion qui exige un mot de passe et un second facteur.
À la fin du guide, https://app.votre-domaine.com n’est accessible qu’après une double authentification sur https://auth.votre-domaine.com. Les secrets sont séparés de la configuration, et vous savez mettre à jour et sauvegarder l’installation.
Commander un serveur
Ce guide s’applique aux serveurs que vous administrez vous-même :
Prérequis
- Un serveur sous Debian 12 ou 13, ou Ubuntu 22.04 ou 24.04
- Un accès SSH avec un utilisateur disposant de
sudo - Docker Engine et Docker Compose, installés avec le guide Installer Docker Engine et Docker Compose
- Caddy, installé avec le guide Caddy en reverse proxy avec HTTPS automatique
- Un domaine dont vous gérez la zone DNS, avec
auth.votre-domaine.cometapp.votre-domaine.compointant versVOTRE_IP_SERVEUR - Une application à protéger, qui écoute uniquement en local, ici sur
127.0.0.1:3000 - Un compte SMTP pour envoyer les codes de vérification et les réinitialisations de mot de passe
Ports utilisés
| Port | Sens | Rôle | À ouvrir |
|---|---|---|---|
| 80/tcp | Entrant | Validation du certificat et redirection vers HTTPS | Oui |
| 443/tcp | Entrant | Portail Authelia et applications protégées | Oui |
| 443/udp | Entrant | HTTP/3 | Recommandé |
| 9091/tcp | Local | Authelia, sur 127.0.0.1 uniquement |
Non |
| 3000/tcp | Local | Application d’exemple | Non |
Authelia fait aussi confiance aux en-têtes X-Forwarded-* que lui transmet le proxy. Son port ne doit donc jamais être accessible depuis Internet.
Étape 1 : créer les dossiers et les secrets
Authelia a besoin de trois secrets : la signature des liens de réinitialisation, la clé de session et la clé de chiffrement de la base. Chacun est placé dans son propre fichier, hors de la configuration.
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_PASSWORDSaisissez dans le dernier fichier le mot de passe de votre compte SMTP, seul sur la première ligne.
Étape 2 : créer le premier utilisateur
Calculez l’empreinte de votre mot de passe. La commande le demande deux fois :
sudo docker run --rm -it authelia/authelia:4.39.28 authelia crypto hash generate argon2Elle affiche une ligne commençant par Digest:. Créez le fichier des utilisateurs :
sudo nano /opt/authelia/config/users.ymlCopiez uniquement la valeur qui commence par $argon2id$, entre apostrophes :
users:
VOTRE_USER:
disabled: false
displayname: 'Admin'
password: '$argon2id$v=19$m=65536,t=3,p=4$...'
email: 'admin@votre-domaine.com'
groups:
- 'admins'Cette adresse e-mail reçoit les codes de vérification : elle doit être valide.
Étape 3 : écrire la configuration
sudo nano /opt/authelia/config/configuration.ymlserver:
address: 'tcp://:9091/'
log:
level: 'info'
totp:
issuer: 'auth.votre-domaine.com'
authentication_backend:
file:
path: '/config/users.yml'
password:
algorithm: 'argon2'
session:
cookies:
- domain: 'votre-domaine.com'
authelia_url: 'https://auth.votre-domaine.com'
default_redirection_url: 'https://app.votre-domaine.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.votre-domaine.com:587'
username: 'authelia@votre-domaine.com'
sender: 'Authelia <authelia@votre-domaine.com>'
access_control:
default_policy: 'deny'
rules:
- domain: 'app.votre-domaine.com'
policy: 'two_factor'| Section | Rôle |
|---|---|
authentication_backend |
Comptes lus dans users.yml, mots de passe en Argon2id |
session.cookies |
Domaine protégé et adresse du portail, obligatoirement en HTTPS |
storage |
Base SQLite, adaptée à une seule instance d’Authelia |
regulation |
Blocage temporaire après trois échecs en deux minutes |
notifier |
Envoi des e-mails. submission:// utilise STARTTLS, submissions:// utilise TLS direct |
access_control |
Tout est refusé, sauf ce qu’une règle autorise |
Étape 4 : démarrer Authelia
sudo nano /opt/authelia/compose.yamlservices:
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"Le conteneur fonctionne avec un utilisateur sans privilèges. Donnez-lui accès à ses fichiers et à personne d’autre :
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 {} +Validez la configuration, puis démarrez le service :
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/healthLa validation doit afficher Configuration parsed and loaded successfully without errors. Les journaux doivent contenir Listening for non-TLS connections, et la dernière commande doit renvoyer {"status":"OK"}.
Le trafic entre Caddy et Authelia reste sur la boucle locale du serveur. Les visiteurs, eux, n’accèdent au portail qu’en HTTPS.
Étape 5 : configurer Caddy
Si vous utilisez UFW, autorisez les ports web :
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udpAjoutez ces deux sites dans /etc/caddy/Caddyfile, ou dans un fichier de /etc/caddy/sites/ :
auth.votre-domaine.com {
reverse_proxy 127.0.0.1:9091
}
app.votre-domaine.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 interroge Authelia avant chaque requête. Si l’accès est accepté, Caddy copie l’identité de l’utilisateur dans les en-têtes Remote-* puis transmet la requête à l’application. Sinon, il renvoie la réponse d’Authelia, en général une redirection vers le portail.
Validez et appliquez :
sudo caddy fmt --overwrite /etc/caddy/Caddyfile
sudo -u caddy caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
sudo systemctl reload caddyÉtape 6 : enregistrer le second facteur
- Ouvrez
https://app.votre-domaine.comdans une fenêtre de navigation privée. Vous arrivez sur le portail. - Connectez-vous avec
VOTRE_USERet le mot de passe choisi à l’étape 2. - Cliquez sur Enregistrer l’appareil.
- Saisissez le code à usage unique reçu par e-mail pour confirmer votre identité.
- Ajoutez un mot de passe à usage unique avec votre application TOTP, ou une clé de sécurité WebAuthn.
- Validez le second facteur : vous êtes redirigé vers l’application.
Vous pourrez ajouter d’autres appareils depuis les Réglages du portail. Enregistrez au moins deux méthodes si possible, pour ne pas dépendre d’un seul appareil.
Vérifier le résultat
curl -si https://app.votre-domaine.com | grep -iE '^(HTTP|location)'
sudo ss -ltnp | grep -E ':(3000|9091) 'La première commande doit renvoyer un code 302 et une adresse https://auth.votre-domaine.com/ avec un paramètre rd. La seconde doit montrer 127.0.0.1 uniquement.
Depuis votre poste, http://VOTRE_IP_SERVEUR:3000 et http://VOTRE_IP_SERVEUR:9091 ne doivent pas répondre. Faites enfin ces contrôles dans une fenêtre privée :
- le mot de passe seul ne donne pas accès à l’application ;
- un code TOTP erroné est refusé ;
- après déconnexion du portail, l’application redemande une authentification.
Refaites ces essais après chaque modification du proxy ou des règles d’accès.
Ajouter des services et affiner les règles
Pour protéger un autre service, ajoutez un site Caddy avec le même bloc forward_auth, puis une règle Authelia. Les règles sont lues dans l’ordre et la première qui correspond s’applique.
access_control:
default_policy: 'deny'
rules:
- domain: 'status.votre-domaine.com'
resources:
- '^/api/health$'
policy: 'bypass'
- domain: 'admin.votre-domaine.com'
subject:
- 'group:admins'
policy: 'two_factor'
- domain: 'app.votre-domaine.com'
policy: 'two_factor'| Politique | Effet |
|---|---|
deny |
Accès refusé |
bypass |
Aucune authentification : à réserver à des chemins réellement publics |
one_factor |
Mot de passe demandé |
two_factor |
Mot de passe et second facteur demandés |
Tous les services doivent se trouver sous le domaine déclaré dans session.cookies. Pour ajouter un utilisateur, complétez users.yml. Après toute modification de la configuration ou des utilisateurs, redémarrez Authelia :
cd /opt/authelia
sudo docker compose restart autheliaLes sessions sont gardées en mémoire : ce redémarrage déconnecte tout le monde.
Mettre à jour Authelia
Lisez les notes de version, sauvegardez, puis remplacez le numéro de version dans compose.yaml :
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 autheliaAu démarrage, Authelia migre automatiquement sa base vers le schéma de la nouvelle version. La sauvegarde préalable est donc votre retour arrière. Refaites ensuite les contrôles de la section de vérification.
Sauvegarder et restaurer
Le dossier /opt/authelia contient tout l’état de l’installation : configuration, utilisateurs, base SQLite et secrets. Arrêtez brièvement le service pour obtenir une copie cohérente :
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"Cette archive contient vos secrets et les empreintes des mots de passe. Copiez-la hors du serveur, dans un emplacement chiffré.
Pour vérifier qu’elle est exploitable sans toucher à l’instance en service, remplacez le nom de l’archive puis contrôlez la clé de chiffrement sur la copie :
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-testLe résultat attendu est Storage Encryption Key Validation: SUCCESS.
Pour restaurer, sur un serveur où Docker et Caddy sont en place :
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 -dEn cas de problème
Commencez toujours par les journaux :
cd /opt/authelia
sudo docker compose logs --tail=100 autheliasecrets: error loading secret path /secrets/...
Le fichier indiqué est absent ou illisible. Vérifiez son nom, puis reprenez les commandes chown et chmod de l’étape 4.
notifier: please ensure only one of the 'smtp' or 'filesystem' notifier is configured
Vous utilisez filesystem alors que AUTHELIA_NOTIFIER_SMTP_PASSWORD_FILE est encore présent dans compose.yaml. Retirez cette ligne, puis relancez sudo docker compose up -d.
One or more providers had fatal failures performing startup checks
Un service requis a échoué au démarrage. Le plus souvent, Authelia ne parvient pas à joindre ou à utiliser le serveur SMTP. Les lignes d’erreur précédentes donnent la cause : adresse, port, identifiants ou port sortant bloqué.
the configured encryption key does not appear to be valid for this database
STORAGE_ENCRYPTION_KEY ne correspond pas à celle qui a servi à créer la base. Remettez la bonne clé depuis votre sauvegarde. Pour la changer volontairement, utilisez la commande authelia storage encryption change-key.
the system clock is not synchronized accurately enough with the configured NTP server
L’horloge du serveur dérive, ce qui rendrait les codes TOTP invalides. Contrôlez la synchronisation :
timedatectl statusTarget URL does not appear to have a relevant session cookies configuration
Le domaine de l’application n’est pas couvert par session.cookies. Vérifiez domain dans configuration.yml et le nom utilisé dans le Caddyfile.
Target URL ... has an insecure scheme
La requête arrive en HTTP. Toutes les applications protégées doivent être servies en HTTPS. Vérifiez que le site Caddy porte bien un nom de domaine public, sans préfixe http://.
Access to '...' is forbidden to user '...'
L’utilisateur est connecté, mais aucune règle ne l’autorise. Vérifiez l’ordre des règles, le domaine et les groupes dans users.yml.
Le mot de passe est refusé alors qu’il est correct
Après plusieurs échecs, le compte ou l’adresse IP est bloqué pendant ban_time. Attendez la fin du délai, ou levez le blocage du compte :
cd /opt/authelia
sudo docker compose exec authelia authelia storage bans user revoke VOTRE_USER --config /config/configuration.ymlPour une adresse IP, utilisez authelia storage bans ip revoke VOTRE_IP.
Erreur 502 dans le navigateur
Caddy ne joint pas Authelia ou l’application. Testez les deux en local :
curl -fsS http://127.0.0.1:9091/api/health
curl -I http://127.0.0.1:3000