Authentik self-hosted: SSO per le tue applicazioni

Un solo accesso per tutte le applicazioni ospitate

Authentik è un server SSO (single sign-on) self-hosted: gli utenti effettuano l'accesso una sola volta e ogni applicazione protetta lo accetta, invece di richiedere una password propria. L'installazione usa un file Docker Compose ufficiale e due secret generati. La parte che richiede più attenzione viene dopo: configurare un reverse proxy per raggiungerlo 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 server esegue anche l'outpost incorporato, il componente che risponde alla domanda "questa richiesta proviene da un utente autenticato?" per ogni applicazione protetta. La versione 2026.8.5 è la release corrente al 25 October 2026. È stata pubblicata il 21 October 2026 come patch più recente della serie 2026.8, iniziata con 2026.8.0 il 18 August, e sostituisce la versione 2026.8.4 del 14 October come tag dell'immagine predefinito nel file Compose ufficiale. 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. Verificarlo con docker compose version. Se il comando restituisce un errore invece della versione, installare il plugin prima di procedere. Le nozioni di base sono descritte 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 costruisce gli URL di reindirizzamento in base al nome host utilizzato dal browser.

Eseguire lo stack con un utente ordinario appartenente al gruppo docker, non come root. L'appartenenza a questo gruppo equivale ai privilegi root sull'host. Assegnarla quindi a un solo account di deployment e a nessun altro, come descritto in account utente con privilegi minimi su un VPS.

Installazione 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, tutti attivi, con postgresql che restituisce healthy quando il relativo controllo ha esito positivo. Il primo avvio esegue le migrazioni del database, quindi attendi un minuto prima di verificare che l'interfaccia web risponda.

Entrambi i valori generati sono importanti, per motivi diversi. PG_PASS è la password di PostgreSQL. La documentazione di installazione di Authentik specifica che le password più lunghe di 99 caratteri non sono supportate, quindi mantieni sotto questo limite ogni password scelta manualmente; quella generata è molto più breve. AUTHENTIK_SECRET_KEY è la chiave che Authentik usa per firmare i cookie e la documentazione di configurazione specifica che modificarla invalida le sessioni attive; una nuova chiave disconnette quindi tutti gli utenti autenticati. Mantieni .env con permessi 600 e conserva una copia in un luogo sicuro insieme ai backup, così un ripristino utilizzerà la stessa chiave del server originale.

Il file Compose contrassegna entrambi i valori come obbligatori con la sintassi ${VAR:?message}: ${PG_PASS:?database password required} nel servizio PostgreSQL e ${AUTHENTIK_SECRET_KEY:?secret key required} nei servizi server e worker. Compose rifiuta quindi di avviarsi se il file non è presente. L'esecuzione di docker compose up -d dalla directory errata stampa una riga come required variable AUTHENTIK_SECRET_KEY is missing a value: secret key required e si interrompe. Il messaggio indica un problema di percorso, non un problema di configurazione.

I valori dell’ambiente che contano

Tutto il resto va nello stesso file .env. Authentik associa il doppio carattere di sottolineatura a una chiave di configurazione annidata, quindi AUTHENTIK_EMAIL__HOST imposta email.host. Un singolo carattere di sottolineatura non viene associato alla chiave annidata. È il motivo più comune per cui un’impostazione sembra non avere effetto.

• AUTHENTIK_BOOTSTRAP_PASSWORD imposta al primo avvio la password dell’utente akadmin integrato, 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 localhost sulla porta 25. Di conseguenza, l’invio delle email per la reimpostazione della password termina 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. In seguito, ripristinalo a 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 secret memorizzati in un file in chiaro. Proteggi quindi la directory come qualsiasi altro archivio di credenziali. Un password manager, ad esempio un’istanza self-hosted di Vaultwarden, è una scelta migliore per conservare la copia di recupero 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 predefinito akadmin. Se hai già impostato AUTHENTIK_BOOTSTRAP_PASSWORD, questo passaggio è completato e vieni portato direttamente alla pagina di accesso.

Crea un normale utente amministratore personale in Directory, quindi in Users, aggiungilo al gruppo authentik Admins ed effettua l'accesso con quell'account. Mantieni akadmin come account di emergenza, con una password lunga conservata offline. Se un flow o uno stage configurato male dovesse impedirti l'accesso, docker compose run --rm server create_recovery_key 10 akadmin, eseguito da /opt/authentik, stampa un link che effettua direttamente l'accesso come akadmin. Chiunque disponga di quel link ha lo stesso livello di accesso, quindi trattalo come una password. Usare ogni giorno un account integrato condiviso rende inutilizzabile l'audit log, perché ogni evento indica akadmin e non identifica l'utente. Questo vale anche per i sistemi a valle di Authentik: una soluzione come un harness OneCLI self-hosted che assegna a ogni persona il proprio agent produce un audit trail leggibile solo se l'identità che vi arriva appartiene a una singola persona, non a un account condiviso dall'intero team.

Configura Authentik dietro il reverse proxy

Pubblicare la porta 9000 su Internet funziona, ma vuoi usare TLS (Transport Layer Security) e un hostname reale. Se esegui già la configurazione descritta in Traefik come reverse proxy per più applicazioni Compose, collega Authentik alla stessa rete esterna proxy tramite un file di override. Crea 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

Applicalo con docker compose up -d. Compose unisce automaticamente il file di override, quindi il servizio server conserva tutto il contenuto del file ufficiale e acquisisce anche le label. Verifica con curl -I https://auth.example.com/if/user/, che dovrebbe restituire HTTP/2 200. Un 404 page not found da Traefik indica che nessun router ha gestito la richiesta. Verifica che le label siano state applicate al container, che la regola Host() corrisponda esattamente all'hostname e che la richiesta sia arrivata sull'entry point HTTPS su cui il router è in ascolto.

Quando l'hostname funziona, associa le porte pubblicate a 127.0.0.1 nel file di override, in modo che l'unico accesso passi dal proxy.

Proteggere un'app con forward auth

Il proxy provider di Authentik dispone di tre modalità. Scegliere quella errata può costare un'ora di lavoro. Proxy significa che è lo stesso outpost a inoltrare il traffico all'applicazione upstream. Forward auth (single application) significa che il reverse proxy continua a inoltrare il traffico e chiede ad Authentik soltanto se la richiesta proviene da un utente autenticato. Forward auth (domain level) protegge tutte le applicazioni appartenenti a un unico dominio padre con un solo provider, ma richiede di definire regole di autorizzazione per ogni applicazione. Con Traefik davanti, è necessario usare forward auth (single application). Se serve un'applicazione concreta su cui fare pratica, un workspace AFFiNE self-hosted è un buon primo candidato: è il tipo di strumento interno che si vuole rendere raggiungibile dai propri dispositivi e da nessun altro. Un'applicazione per il team rende il caso ancora più evidente: collocare un help desk Chatwoot self-hosted dietro lo stesso provider consente a chiunque risponda alla posta in arrivo di autenticarsi una volta al giorno, invece di condividere un'altra password.

Nell'interfaccia web, aprire Applications e quindi Providers, creare un Proxy Provider, scegliere la modalità forward auth single application e impostare l'host esterno su https://app.example.com. Creare un'Application che punti a quel provider. Poi aprire Outposts, modificare authentik Embedded Outpost e aggiungere la nuova applicazione alle applicazioni selezionate. L'outpost risponde soltanto per le applicazioni che gli sono state assegnate. Se si salta quest'ultimo passaggio, un provider configurato correttamente non restituisce alcuna risposta.

Definire il middleware una sola volta, sul container Authentik, e richiamarlo da 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-entitlements,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 alla richiesta che invia all'upstream. Se lo si omette, l'applicazione è comunque protetta, ma non riceve l'identità dell'utente. Di conseguenza, tutto ciò che legge X-authentik-username per eseguire l'accesso automatico resta non autenticato. Questo limite è particolarmente evidente davanti a un'applicazione che mantiene una propria sessione di accesso, come un tracker di allenamento openGym self-hosted con accesso tramite passkey: gli header determinano se per la stessa pagina viene mostrato un solo prompt o due.

L'applicazione protetta richiede due router, non uno:

    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 è quello che viene spesso omesso. Dopo l'accesso, Authentik rimanda il browser a un percorso sotto /outpost.goauthentik.io/ sull'hostname dell'applicazione, non su auth.example.com. Senza un router che inoltri quel prefisso di percorso al servizio Authentik, la richiesta raggiunge l'applicazione, che risponde con 404, e l'accesso non viene completato. Il valore più alto di priority fa sì che la regola specifica del percorso abbia precedenza sulla regola semplice Host() nello stesso dominio.

Eseguire il test in una finestra privata del browser. Il browser dovrebbe essere reindirizzato a auth.example.com, consentire l'accesso e poi 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.

Gli errori che si verificano più spesso

Reindirizzamento continuo 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 e ogni ritorno viene interpretato come una nuova richiesta anonima. Correggi l'host esterno ed elimina i cookie per entrambi i domini prima di ripetere 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 fa riferimento a un middleware inesistente. Traefik non segnala questo errore, quindi un refuso 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.

Errore 403 da Authentik dopo un accesso riuscito. L'utente è autenticato, ma non autorizzato: all'applicazione è associata una policy, oppure è richiesto un 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ù datato, supportato da Red Hat, ed è la scelta più solida per gli scenari di gestione delle identità aziendali tradizionali: federazione SAML avanzata, gestione degli accessi tramite più identity provider esterni contemporaneamente ed esportazione e importazione dei realm come percorso di migrazione documentato. Per alcune organizzazioni, anche la disponibilità di supporto commerciale è un elemento importante. Il compromesso è che Keycloak non include un proxy, quindi per proteggere un'applicazione che non supporta né OIDC (OpenID Connect) né SAML è necessario eseguire insieme un componente come oauth2-proxy. Il proxy provider integrato di Authentik svolge già questa funzione, ed è per questo che la maggior parte degli utenti che gestiscono autonomamente 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 dump non contiene una copia di AUTHENTIK_SECRET_KEY e il ripristino con una chiave diversa invalida tutte le sessioni attive; conservare la chiave originale permette quindi al server ripristinato di continuare a funzionare come prima.

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. Se non imposti AUTHENTIK_TAG, la versione viene ricavata dal valore predefinito scritto direttamente in compose.yml; scaricare una copia più recente di quel file costituisce quindi l'aggiornamento, ed è la procedura descritta dalla documentazione ufficiale. Leggi prima le note di rilascio. Authentik usa versioni basate sulla data e, a ottobre 2026, la documentazione specifica che gli aggiornamenti devono seguire la sequenza delle release principali: passa alla patch più recente della serie in uso, quindi attraversa ogni serie successiva nell'ordine previsto senza saltarne nessuna. Authentik non supporta il downgrade, quindi crea il dump del database prima del pull, non dopo.

FAQ

Authentik è gratuito per l'hosting autonomo?

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

Serve Traefik per usare 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 anziché verso l'applicazione.

Perché l'applicazione protetta passa continuamente dalla pagina di accesso all'errore?

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

Quanta RAM richiede Authentik?

A ottobre 2026, il requisito minimo documentato è di 2 core CPU e 2 GB di RAM, per PostgreSQL, il server e il worker nel loro insieme. Su un sistema con 2 GB, la pressione sulla memoria può attivare l'OOM killer del kernel, che termina il processo con il punteggio di badness più alto: approssimativamente la quota di memoria consentita che utilizza, più il relativo oom_score_adj. Se il processo terminato è il worker, 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.