IT

Applicazioni

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.

9 min di lettura, aggiornato il 18 novembre 2026

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.com e app.tuo-dominio.com che puntano a IP_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.

Terminale
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

Nell'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:

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

Mostra una riga che inizia con Digest:. Crea il file degli utenti:

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

Copia solo il valore che inizia con $argon2id$, tra apici:

YAML
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

Terminale
sudo nano /opt/authelia/config/configuration.yml
YAML
server:
  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

Terminale
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"

Il container funziona con un utente senza privilegi. Dagli accesso ai suoi file e a nessun altro:

Terminale
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:

Terminale
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

La 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:

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

Aggiungi questi due siti in /etc/caddy/Caddyfile, oppure in un file di /etc/caddy/sites/:

caddyfile
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:

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

Passo 6: registrare il secondo fattore

  1. Apri https://app.tuo-dominio.com in una finestra di navigazione privata. Arrivi sul portale.
  2. Accedi con TUO_USER e la password scelta al passo 2.
  3. Fai clic su Registra dispositivo.
  4. Inserisci il codice monouso ricevuto via e-mail per confermare la tua identità.
  5. Aggiungi una Password Unica con la tua app TOTP, oppure una Chiave Di Sicurezza WebAuthn.
  6. 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

Terminale
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.

YAML
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:

Terminale
cd /opt/authelia
sudo docker compose restart authelia

Le 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:

Terminale
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

All'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:

Terminale
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:

Terminale
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

Il risultato atteso è Storage Encryption Key Validation: SUCCESS.

Per ripristinare, su un server in cui Docker e Caddy sono già presenti:

Terminale
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

In caso di problemi

Parti sempre dai log:

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

secrets: 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:

Terminale
timedatectl status

Target 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:

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

Per 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:

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

Riferimenti