Authentik: SSO self-hosted con Docker Compose

Un solo accesso per ogni applicazione ospitata

Authentik è un server SSO (single sign-on) self-hosted: gli utenti effettuano l'accesso una sola volta e ogni applicazione protetta accetta quella sessione, senza richiedere una password separata. L'installazione usa un file ufficiale Docker Compose e due segreti generati. La parte più complessa viene dopo: configurare un reverse proxy affinché punti ad Authentik e proteggere un'applicazione esistente con forward auth.

Authentik viene distribuito come tre servizi nel file Compose: un database PostgreSQL, un processo server e un processo worker. Il container del server esegue anche l'outpost integrato, il componente che verifica se la richiesta è autenticata per ogni applicazione protetta. La versione 2026.5 è la release corrente a luglio 2026 e il progetto richiede un host con almeno 2 core CPU e 2 GB di RAM. Consideralo il requisito minimo. PostgreSQL e il worker continuano a utilizzare memoria dopo che il server è rimasto attivo per un giorno.

Cosa serve prima di iniziare

È necessario Docker Engine con il plugin Compose v2. Puoi verificarne la presenza con docker compose version. Se viene visualizzato un errore invece della versione, installa il plugin prima di procedere; le nozioni di base sono illustrate in esecuzione di applicazioni con Docker Compose su un VPS. È inoltre necessario un record DNS A che punti al server, auth.example.com negli esempi seguenti, perché Authentik crea gli URL di reindirizzamento usando il nome host utilizzato dal browser.

Esegui lo stack con un utente normale appartenente al gruppo docker, non come root. L'appartenenza a questo gruppo equivale all'accesso root sull'host. Assegnala quindi a un solo account di distribuzione e a nessun altro, come descritto in account utente con privilegi minimi su un VPS.

Installare con il file Compose ufficiale

sudo install -d -o "$USER" -g "$USER" /opt/authentik
cd /opt/authentik
wget https://docs.goauthentik.io/compose.yml
echo "PG_PASS=$(openssl rand -base64 36 | tr -d '\n')" >> .env
echo "AUTHENTIK_SECRET_KEY=$(openssl rand -base64 60 | tr -d '\n')" >> .env
docker compose pull
docker compose up -d

docker compose ps dovrebbe elencare tre container, con postgresql che segnala healthy e server e worker che segnala running. Il primo avvio esegue le migrazioni del database, quindi attendi un minuto prima che l'interfaccia web risponda.

Entrambi i valori generati sono importanti, per motivi diversi. PG_PASS è la password PostgreSQL e ha un limite massimo di 99 caratteri. AUTHENTIK_SECRET_KEY firma le sessioni e i token; se lo cambi in seguito, tutti gli utenti vengono disconnessi e tutti i token API emessi diventano non validi. Mantieni .env con la modalità 600 e conservane una copia in un luogo sicuro, perché un database ripristinato senza la chiave segreta corrispondente è un database a cui nessuno può accedere.

Il file Compose legge entrambi i valori usando la sintassi ${PG_PASS:?database password required}, quindi Compose rifiuta l'avvio se il file manca. Eseguendo docker compose up -d dalla directory errata viene visualizzato required variable AUTHENTIK_SECRET_KEY is missing a value: secret key required e l'esecuzione si interrompe. Il messaggio indica un problema relativo al percorso, non alla configurazione.

I valori dell'ambiente importanti

Tutto il resto va nello stesso file .env. Authentik associa due caratteri di sottolineatura a una chiave di configurazione annidata, quindi AUTHENTIK_EMAIL__HOST imposta email.host. Un singolo carattere di sottolineatura viene ignorato senza avvisi. Questa è la causa più comune per cui un'impostazione sembra non avere effetto.

• AUTHENTIK_BOOTSTRAP_PASSWORD imposta la password dell'utente akadmin integrato al primo avvio, così non è necessario inserirla in un modulo web pubblico. AUTHENTIK_BOOTSTRAP_EMAIL e AUTHENTIK_BOOTSTRAP_TOKEN impostano allo stesso modo l'indirizzo di quell'utente e un token API.
• COMPOSE_PORT_HTTP e COMPOSE_PORT_HTTPS spostano le porte pubblicate rispetto ai valori predefiniti 9000 e 9443.
• AUTHENTIK_EMAIL__HOST, AUTHENTIK_EMAIL__PORT, AUTHENTIK_EMAIL__USERNAME, AUTHENTIK_EMAIL__PASSWORD, AUTHENTIK_EMAIL__USE_TLS e AUTHENTIK_EMAIL__FROM configurano la posta in uscita. Senza questi valori, Authentik prova a usare localhost sulla porta 25, quindi le e-mail per la reimpostazione della password terminano con un errore di connessione nel log del worker.
• AUTHENTIK_LOG_LEVEL=debug abilita il livello di dettaglio necessario quando un flusso di accesso non funziona correttamente. Al termine, ripristina info.
• Per impostazione predefinita, AUTHENTIK_ERROR_REPORTING__ENABLED è false. Impostalo su true solo se accetti di inviare i report degli arresti anomali al fornitore.

Questi sono segreti memorizzati in un file non cifrato. Tratta quindi la directory come qualsiasi altro archivio di credenziali. Un gestore di password, ad esempio un'istanza di Vaultwarden autogestita, è un luogo più sicuro per conservare la copia di ripristino rispetto a una nota sul laptop.

Primo accesso e account amministratore

Apri http://SERVER_IP:9000 in un browser. Authentik mostra la procedura di configurazione iniziale e chiede di impostare una password per l'utente akadmin predefinito. Se hai già impostato AUTHENTIK_BOOTSTRAP_PASSWORD, questo passaggio è completato e accedi direttamente alla pagina di login.

Crea un normale utente amministratore per te in Directory, quindi in Users, aggiungilo al gruppo authentik Admins e accedi con questo account. Mantieni akadmin come account di emergenza, con una password lunga archiviata offline. L'uso quotidiano di un account predefinito condiviso compromette il log di audit, perché ogni evento riporta akadmin e non indica chi ha eseguito l'operazione.

Inserire Authentik dietro il reverse proxy

Pubblicare la porta 9000 su Internet funziona, ma sono necessari TLS (Transport Layer Security) e un hostname reale. Se utilizzate già la configurazione descritta in Traefik come reverse proxy per più app Compose, collegate Authentik alla stessa rete esterna proxy con un file di override. Create docker-compose.override.yml accanto a compose.yml:

services:
  server:
    networks:
      - default
      - proxy
    labels:
      traefik.enable: "true"
      traefik.docker.network: proxy
      traefik.http.routers.authentik.rule: Host(`auth.example.com`)
      traefik.http.routers.authentik.entrypoints: websecure
      traefik.http.routers.authentik.tls.certresolver: le
      traefik.http.services.authentik.loadbalancer.server.port: "9000"

networks:
  proxy:
    external: true

Applicatelo con docker compose up -d. Compose unisce automaticamente il file di override, quindi il servizio server mantiene tutte le impostazioni del file ufficiale e acquisisce le label. Verificate con curl -I https://auth.example.com/if/user/, che dovrebbe rispondere a HTTP/2 200. Un 404 page not found da Traefik indica che il container non è collegato alla rete proxy e che Traefik non può instradare il traffico verso un container che non riesce a raggiungere.

Quando l'hostname funziona, associate le porte pubblicate a 127.0.0.1 nel file di override, così l'unico accesso passa dal proxy.

Proteggere un'app con forward auth

Il proxy provider di Authentik ha tre modalità e scegliere quella sbagliata può costare un'ora. Proxy significa che è l'outpost stesso a inoltrare il traffico all'applicazione upstream. Forward auth (single application) significa che il reverse proxy continua a gestire il traffico e chiede ad Authentik solo se la richiesta proviene da un utente autenticato. Forward auth (domain level) protegge tutte le applicazioni sotto uno stesso dominio padre con un unico provider, ma richiede regole di autorizzazione specifiche per ogni applicazione. Con Traefik davanti, devi usare forward auth (single application).

Nell'interfaccia web, apri Applications e poi Providers, crea un Proxy Provider, scegli la modalità forward auth single application e imposta l'host esterno su https://app.example.com. Crea un'Application associata a quel provider. Poi apri Outposts, modifica authentik Embedded Outpost e aggiungi la nuova applicazione alle applicazioni selezionate. L'outpost risponde solo per le applicazioni assegnate. Se salti quest'ultimo passaggio, un provider configurato correttamente non restituisce alcuna risposta.

Definisci il middleware una sola volta, sul container Authentik, e usalo come riferimento per ogni applicazione protetta:

      traefik.http.middlewares.authentik.forwardauth.address: http://server:9000/outpost.goauthentik.io/auth/traefik
      traefik.http.middlewares.authentik.forwardauth.trustForwardHeader: "true"
      traefik.http.middlewares.authentik.forwardauth.authResponseHeaders: X-authentik-username,X-authentik-groups,X-authentik-email,X-authentik-name,X-authentik-uid,X-authentik-jwt,X-authentik-meta-jwks,X-authentik-meta-outpost,X-authentik-meta-provider,X-authentik-meta-app,X-authentik-meta-version

authResponseHeaders è l'elenco degli header che Traefik copia dalla risposta di Authentik nella richiesta inviata all'upstream. Se lo ometti, l'applicazione è comunque protetta, ma non identifica l'utente. Di conseguenza, tutto ciò che legge X-authentik-username per eseguire l'accesso automatico resta disconnesso.

L'applicazione protetta richiede due router, non uno solo:

    labels:
      traefik.enable: "true"
      traefik.http.routers.myapp.rule: Host(`app.example.com`)
      traefik.http.routers.myapp.entrypoints: websecure
      traefik.http.routers.myapp.tls.certresolver: le
      traefik.http.routers.myapp.middlewares: authentik@docker
      traefik.http.routers.myapp-auth.rule: Host(`app.example.com`) && PathPrefix(`/outpost.goauthentik.io/`)
      traefik.http.routers.myapp-auth.entrypoints: websecure
      traefik.http.routers.myapp-auth.tls.certresolver: le
      traefik.http.routers.myapp-auth.priority: "15"
      traefik.http.routers.myapp-auth.service: authentik

Il secondo router è la parte che viene spesso omessa. Dopo l'accesso, Authentik rimanda il browser a un percorso sotto /outpost.goauthentik.io/ sull'hostname dell'applicazione, non su auth.example.com. Se non esiste un router che invia quel prefisso di percorso al servizio Authentik, la richiesta arriva all'applicazione, che risponde con 404, e l'accesso non viene completato. Il valore priority più alto fa prevalere la regola specifica del percorso sulla regola semplice Host() per lo stesso dominio.

Esegui il test in una finestra del browser privata. Dovresti essere reindirizzato a auth.example.com, effettuare l'accesso e tornare all'applicazione. docker compose logs -f server sul lato Authentik stampa un evento di autorizzazione per ogni tentativo e indica se la richiesta ha raggiunto Authentik.

I problemi che incontrerai effettivamente

Ciclo infinito di reindirizzamento tra l'applicazione e la pagina di accesso. L'host esterno configurato nel provider non corrisponde a quello utilizzato dal browser, in genere http:// nel provider rispetto a https:// nella barra degli indirizzi. Il cookie di sessione viene quindi impostato per un'origine diversa, perciò ogni ritorno viene interpretato come una nuova richiesta anonima. Correggi l'host esterno ed elimina i cookie per entrambi i domini prima di eseguire nuovamente il test.

404 su /outpost.goauthentik.io/start. Manca il router outpost oppure la sua priorità è inferiore a quella del router catch-all per quell'host.

L'applicazione viene caricata senza richiedere l'accesso. L'etichetta middlewares indica un middleware inesistente. Traefik non mostra avvisi in questo caso, quindi un errore di battitura in authentik@docker fa semplicemente sì che non venga eseguito alcun middleware. Apri la dashboard di Traefik e verifica che il router elenchi il middleware.

403 da Authentik dopo un accesso riuscito. L'utente è autenticato, ma non autorizzato: l'applicazione applica un'associazione a una policy o un requisito di gruppo che l'utente non soddisfa. Il log Events nell'interfaccia di amministrazione indica la policy che ha negato l'accesso.

Quando Keycloak è la scelta più adatta

Keycloak è il progetto più maturo, supportato da Red Hat, e rappresenta la scelta più solida per gli scenari di identità aziendale tradizionali: federazione SAML avanzata, gestione degli accessi tramite più provider di identità esterni contemporaneamente ed esportazione e importazione dei realm come percorso di migrazione documentato. Per alcune organizzazioni, anche il supporto commerciale è un fattore importante. Lo svantaggio è che Keycloak non dispone di un proxy integrato. Per proteggere un'applicazione che non supporta OIDC (OpenID Connect), è quindi necessario eseguire un componente come oauth2-proxy insieme a Keycloak. Il provider proxy integrato di Authentik svolge già questa funzione ed è integrato nel prodotto. Per questo motivo, la maggior parte degli utenti che gestiscono autonomamente ambienti con applicazioni eterogenee sceglie Authentik.

Backup e aggiornamenti

Tre elementi rendono possibile un ripristino: il database PostgreSQL, la directory ./data e .env.

cd /opt/authentik
docker compose exec -T postgresql pg_dump -U authentik authentik | gzip > authentik-$(date +%F).sql.gz

Conserva insieme il dump e .env. Il solo dump non è sufficiente, perché la chiave segreta che protegge i dati delle sessioni e dei token si trova in .env.

Gli aggiornamenti consistono nella modifica di un tag. Imposta AUTHENTIK_TAG in .env sulla release desiderata, quindi esegui docker compose pull seguito da docker compose up -d. Leggi prima le note di rilascio, perché Authentik usa versioni basate sulla data e alcune release includono migrazioni che richiedono di partire da quella precedente. Crea il dump del database prima del pull, non dopo.

FAQ

Authentik è gratuito se lo gestisco autonomamente?

L'edizione open source è gratuita e include tutto ciò che è descritto sopra: il provider proxy, forward auth, OIDC (OpenID Connect), SAML e il motore dei flussi. Un livello enterprise a pagamento aggiunge supporto e alcune funzionalità enterprise, ma per questa configurazione non serve alcuna licenza.

È necessario usare Traefik con Authentik?

No. Forward auth funziona con nginx tramite auth_request e con Caddy tramite forward_auth. Il modello è lo stesso in ogni caso: il reverse proxy chiede ad Authentik di verificare ogni richiesta e il prefisso del percorso /outpost.goauthentik.io/ sull'hostname protetto deve essere instradato verso Authentik, non verso l'applicazione.

Perché la mia applicazione protetta alterna continuamente la pagina di accesso e un errore?

L'host esterno configurato nel provider proxy non corrisponde all'URL utilizzato dal browser, nella maggior parte dei casi http invece di https. Il cookie di sessione viene emesso per un'origine e letto da un'altra, quindi Authentik rileva una richiesta anonima ogni volta. Correggi l'host esterno, quindi elimina i cookie per entrambi gli hostname prima di eseguire nuovamente il test.

Quanta RAM richiede Authentik?

A luglio 2026, il minimo documentato è di 2 core CPU e 2 GB di RAM, per PostgreSQL, il server e il worker insieme. Su un sistema con 2 GB, il worker è il primo processo terminato dal kernel in caso di pressione sulla memoria. Il sintomo è l'interruzione delle attività in background e delle email in uscita, mentre la pagina di accesso continua a funzionare. Assegna 4 GB se lo stesso server esegue anche le applicazioni che stai proteggendo.