Proteggere i tuoi servizi con Authelia e Caddy
Distribuisci Authelia su Debian o Ubuntu con Docker e Caddy: portale di autenticazione, doppia autenticazione, segreti separati, regole di accesso, aggiornamenti e backup.
In questa pagina
I tuoi valori
Inseriscili una volta: i comandi della guida si aggiornano.
Questa guida spiega come mettere Authelia davanti alle tue applicazioni web. Il reverse proxy Caddy chiede ad Authelia, a ogni richiesta, se il visitatore può passare. Se non è identificato, viene inviato a un portale di accesso che richiede una password e un secondo fattore.
Al termine della guida, https://app.tuo-dominio.com è accessibile solo dopo una doppia autenticazione su https://auth.tuo-dominio.com. I segreti sono separati dalla configurazione e sai aggiornare ed eseguire il backup dell'installazione.
Ordina un Server
Questa guida si applica ai server che amministri tu stesso:
Prerequisiti
- Un server con Debian 12 o 13, oppure Ubuntu 22.04 o 24.04
- Un accesso SSH con un utente che dispone di
sudo - Docker Engine e Docker Compose, installati con la guida Installare Docker Engine e Docker Compose
- Caddy, installato con la guida Caddy come reverse proxy con HTTPS automatico
- Un dominio di cui gestisci la zona DNS, con
auth.tuo-dominio.comeapp.tuo-dominio.comche puntano aIP_DEL_TUO_SERVER - Un'applicazione da proteggere, in ascolto solo in locale, qui su
127.0.0.1:3000 - Un account SMTP per inviare i codici di verifica e le reimpostazioni della password
Porte utilizzate
| Porta | Direzione | Ruolo | Da aprire |
|---|---|---|---|
| 80/tcp | In entrata | Validazione del certificato e reindirizzamento a HTTPS | Sì |
| 443/tcp | In entrata | Portale Authelia e applicazioni protette | Sì |
| 443/udp | In entrata | HTTP/3 | Consigliato |
| 9091/tcp | Locale | Authelia, solo su 127.0.0.1 |
No |
| 3000/tcp | Locale | Applicazione di esempio | No |
Authelia si fida anche degli header X-Forwarded-* che gli trasmette il proxy. La sua porta non deve quindi mai essere accessibile da Internet.
Passo 1: creare le cartelle e i segreti
Authelia ha bisogno di tre segreti: la firma dei link di reimpostazione, la chiave di sessione e la chiave di cifratura del database. Ognuno viene collocato nel proprio file, fuori dalla configurazione.
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_PASSWORDNell'ultimo file inserisci la password del tuo account SMTP, da sola sulla prima riga.
Passo 2: creare il primo utente
Calcola l'impronta della tua password. Il comando la chiede due volte:
sudo docker run --rm -it authelia/authelia:4.39.28 authelia crypto hash generate argon2Mostra una riga che inizia con Digest:. Crea il file degli utenti:
sudo nano /opt/authelia/config/users.ymlCopia solo il valore che inizia con $argon2id$, tra apici:
users:
TUO_USER:
disabled: false
displayname: 'Admin'
password: '$argon2id$v=19$m=65536,t=3,p=4$...'
email: 'admin@tuo-dominio.com'
groups:
- 'admins'Questo indirizzo e-mail riceve i codici di verifica: deve essere valido.
Passo 3: scrivere la configurazione
sudo nano /opt/authelia/config/configuration.ymlserver:
address: 'tcp://:9091/'
log:
level: 'info'
totp:
issuer: 'auth.tuo-dominio.com'
authentication_backend:
file:
path: '/config/users.yml'
password:
algorithm: 'argon2'
session:
cookies:
- domain: 'tuo-dominio.com'
authelia_url: 'https://auth.tuo-dominio.com'
default_redirection_url: 'https://app.tuo-dominio.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.tuo-dominio.com:587'
username: 'authelia@tuo-dominio.com'
sender: 'Authelia <authelia@tuo-dominio.com>'
access_control:
default_policy: 'deny'
rules:
- domain: 'app.tuo-dominio.com'
policy: 'two_factor'| Sezione | Ruolo |
|---|---|
authentication_backend |
Account letti da users.yml, password in Argon2id |
session.cookies |
Dominio protetto e indirizzo del portale, obbligatoriamente in HTTPS |
storage |
Database SQLite, adatto a una sola istanza di Authelia |
regulation |
Blocco temporaneo dopo tre errori in due minuti |
notifier |
Invio delle e-mail. submission:// usa STARTTLS, submissions:// usa TLS diretto |
access_control |
Tutto è negato, tranne ciò che una regola autorizza |
Passo 4: avviare 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"Il container funziona con un utente senza privilegi. Dagli accesso ai suoi file e a nessun altro:
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 {} +Convalida la configurazione, poi avvia il servizio:
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 convalida deve mostrare Configuration parsed and loaded successfully without errors. I log devono contenere Listening for non-TLS connections, e l'ultimo comando deve restituire {"status":"OK"}.
Il traffico tra Caddy e Authelia resta sul loopback del server. I visitatori, invece, accedono al portale solo in HTTPS.
Passo 5: configurare Caddy
Se usi UFW, autorizza le porte web:
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udpAggiungi questi due siti in /etc/caddy/Caddyfile, oppure in un file di /etc/caddy/sites/:
auth.tuo-dominio.com {
reverse_proxy 127.0.0.1:9091
}
app.tuo-dominio.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 interroga Authelia prima di ogni richiesta. Se l'accesso è accettato, Caddy copia l'identità dell'utente negli header Remote-*, poi inoltra la richiesta all'applicazione. Altrimenti restituisce la risposta di Authelia, in genere un reindirizzamento al portale.
Convalida e applica:
sudo caddy fmt --overwrite /etc/caddy/Caddyfile
sudo -u caddy caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
sudo systemctl reload caddyPasso 6: registrare il secondo fattore
- Apri
https://app.tuo-dominio.comin una finestra di navigazione privata. Arrivi sul portale. - Accedi con
TUO_USERe la password scelta al passo 2. - Fai clic su Registra dispositivo.
- Inserisci il codice monouso ricevuto via e-mail per confermare la tua identità.
- Aggiungi una Password Unica con la tua app TOTP, oppure una Chiave Di Sicurezza WebAuthn.
- Convalida il secondo fattore: vieni reindirizzato all'applicazione.
Potrai aggiungere altri dispositivi dalle Impostazioni del portale. Se possibile, registra almeno due metodi, per non dipendere da un solo dispositivo.
Verificare il risultato
curl -si https://app.tuo-dominio.com | grep -iE '^(HTTP|location)'
sudo ss -ltnp | grep -E ':(3000|9091) 'Il primo comando deve restituire un codice 302 e un indirizzo https://auth.tuo-dominio.com/ con un parametro rd. Il secondo deve mostrare solo 127.0.0.1.
Dal tuo computer, http://IP_DEL_TUO_SERVER:3000 e http://IP_DEL_TUO_SERVER:9091 non devono rispondere. Esegui infine questi controlli in una finestra privata:
- la sola password non dà accesso all'applicazione;
- un codice TOTP errato viene rifiutato;
- dopo la disconnessione dal portale, l'applicazione richiede di nuovo l'autenticazione.
Ripeti queste prove dopo ogni modifica del proxy o delle regole di accesso.
Aggiungere servizi e affinare le regole
Per proteggere un altro servizio, aggiungi un sito Caddy con lo stesso blocco forward_auth, poi una regola Authelia. Le regole vengono lette in ordine e si applica la prima che corrisponde.
access_control:
default_policy: 'deny'
rules:
- domain: 'status.tuo-dominio.com'
resources:
- '^/api/health$'
policy: 'bypass'
- domain: 'admin.tuo-dominio.com'
subject:
- 'group:admins'
policy: 'two_factor'
- domain: 'app.tuo-dominio.com'
policy: 'two_factor'| Policy | Effetto |
|---|---|
deny |
Accesso negato |
bypass |
Nessuna autenticazione: da riservare a percorsi davvero pubblici |
one_factor |
Viene richiesta la password |
two_factor |
Vengono richiesti password e secondo fattore |
Tutti i servizi devono trovarsi sotto il dominio dichiarato in session.cookies. Per aggiungere un utente, completa users.yml. Dopo ogni modifica della configurazione o degli utenti, riavvia Authelia:
cd /opt/authelia
sudo docker compose restart autheliaLe sessioni sono tenute in memoria: questo riavvio disconnette tutti.
Aggiornare Authelia
Leggi le note di rilascio, esegui il backup, poi sostituisci il numero di versione in 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 autheliaAll'avvio, Authelia migra automaticamente il suo database allo schema della nuova versione. Il backup preliminare è quindi il tuo ritorno alla versione precedente. Ripeti poi i controlli della sezione di verifica.
Backup e ripristino
La cartella /opt/authelia contiene tutto lo stato dell'installazione: configurazione, utenti, database SQLite e segreti. Ferma brevemente il servizio per ottenere una copia coerente:
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"Questo archivio contiene i tuoi segreti e le impronte delle password. Copialo fuori dal server, in una posizione cifrata.
Per verificare che sia utilizzabile senza toccare l'istanza in servizio, sostituisci il nome dell'archivio, poi controlla la chiave di cifratura sulla copia:
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-testIl risultato atteso è Storage Encryption Key Validation: SUCCESS.
Per ripristinare, su un server in cui Docker e Caddy sono già presenti:
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 -dIn caso di problemi
Parti sempre dai log:
cd /opt/authelia
sudo docker compose logs --tail=100 autheliasecrets: error loading secret path /secrets/...
Il file indicato è assente o illeggibile. Controlla il suo nome, poi riesegui i comandi chown e chmod del passo 4.
notifier: please ensure only one of the 'smtp' or 'filesystem' notifier is configured
Stai usando filesystem mentre AUTHELIA_NOTIFIER_SMTP_PASSWORD_FILE è ancora presente in compose.yaml. Rimuovi questa riga, poi rilancia sudo docker compose up -d.
One or more providers had fatal failures performing startup checks
Un servizio richiesto è fallito all'avvio. Il più delle volte, Authelia non riesce a raggiungere o a usare il server SMTP. Le righe di errore precedenti indicano la causa: indirizzo, porta, credenziali o porta in uscita bloccata.
the configured encryption key does not appear to be valid for this database
STORAGE_ENCRYPTION_KEY non corrisponde a quella usata per creare il database. Rimetti la chiave giusta dal tuo backup. Per cambiarla di proposito, usa il comando authelia storage encryption change-key.
the system clock is not synchronized accurately enough with the configured NTP server
L'orologio del server va fuori sincrono, il che renderebbe non validi i codici TOTP. Controlla la sincronizzazione:
timedatectl statusTarget URL does not appear to have a relevant session cookies configuration
Il dominio dell'applicazione non è coperto da session.cookies. Controlla domain in configuration.yml e il nome usato nel Caddyfile.
Target URL ... has an insecure scheme
La richiesta arriva in HTTP. Tutte le applicazioni protette devono essere servite in HTTPS. Verifica che il sito Caddy riporti un nome di dominio pubblico, senza prefisso http://.
Access to '...' is forbidden to user '...'
L'utente è connesso, ma nessuna regola lo autorizza. Controlla l'ordine delle regole, il dominio e i gruppi in users.yml.
La password viene rifiutata anche se è corretta
Dopo diversi errori, l'account o l'indirizzo IP viene bloccato per la durata di ban_time. Attendi la fine del periodo, oppure rimuovi il blocco dell'account:
cd /opt/authelia
sudo docker compose exec authelia authelia storage bans user revoke TUO_USER --config /config/configuration.ymlPer un indirizzo IP, usa authelia storage bans ip revoke TUO_IP.
Errore 502 nel browser
Caddy non raggiunge Authelia o l'applicazione. Testali entrambi in locale:
curl -fsS http://127.0.0.1:9091/api/health
curl -I http://127.0.0.1:3000