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 tutte le applicazioni che si trovano dietro di esso accettano quella sessione, senza richiedere una password separata. L'installazione usa un file Docker Compose ufficiale e due secret generati. La parte che richiede più attenzione viene dopo: configurare un reverse proxy perché punti ad Authentik e inserire un'applicazione esistente dietro 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 integrato, il componente che verifica se la richiesta proviene da un utente autenticato 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. Considera questi valori come il minimo. Dopo un giorno di attività, PostgreSQL e il worker utilizzano entrambi memoria.

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.

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: postgresql deve riportare healthy, mentre server deve riportare worker e running. Al primo avvio vengono eseguite 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 PostgreSQL e ha un limite massimo di 99 caratteri. AUTHENTIK_SECRET_KEY firma sessioni e token; se lo modifichi in seguito, tutti gli utenti vengono disconnessi e tutti i token API emessi vengono invalidati. Imposta .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 forma ${PG_PASS:?database password required}, quindi Compose rifiuta di avviarsi se il file non esiste. Se esegui 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. Questo messaggio indica un problema con il percorso, non con la configurazione.

I valori dell'ambiente rilevanti

Tutto il resto va nello stesso file .env. Authentik associa una doppia sottolineatura a una chiave di configurazione annidata, quindi AUTHENTIK_EMAIL__HOST imposta email.host. Una singola sottolineatura viene ignorata senza avvisi. È 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 devi 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 tenta di usare localhost sulla porta 25, quindi le email 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. Riportalo a info al termine.
• AUTHENTIK_ERROR_REPORTING__ENABLED è impostato su false per impostazione predefinita. Impostalo su true solo se accetti di inviare i report degli arresti anomali al progetto upstream.

Questi sono secret memorizzati in un file in chiaro, quindi proteggi la directory come qualsiasi altro archivio di credenziali. Un password manager, ad esempio un istanza self-hosted di Vaultwarden, è una posizione più sicura 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 guidata di configurazione iniziale e chiede di impostare una password per l’utente akadmin predefinito. Se hai già impostato AUTHENTIK_BOOTSTRAP_PASSWORD, questo passaggio è già completato e passi direttamente alla pagina di accesso.

Crea un normale utente amministratore per te in Directory, quindi Users, aggiungilo al gruppo authentik Admins e accedi con quell'account. Mantieni akadmin come account break-glass, con una password lunga conservata offline. L'uso quotidiano di un account integrato condiviso compromette il registro di audit, perché ogni evento riporta akadmin e non indica chi ha eseguito l'azione. Questo principio vale anche oltre Authentik: una soluzione come un harness OneCLI self-hosted che assegna a ogni persona il proprio agente produce un registro leggibile soltanto se l'identità che vi arriva appartiene a una singola persona, non a un account condiviso da tutto il team.

Metti Authentik dietro il reverse proxy

Pubblicare la porta 9000 su Internet funziona, ma vuoi TLS (transport layer security) e un hostname reale. Se usi già la configurazione descritta in Traefik come reverse proxy per più app 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 tutte le impostazioni del file ufficiale e acquisisce le label. Verifica con curl -I https://auth.example.com/if/user/: dovrebbe rispondere 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 non raggiungibile.

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 ha tre modalità e scegliere quella errata 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 soltanto se la richiesta proviene da un utente autenticato. Forward auth (domain level) protegge tutte le applicazioni di un dominio principale con un unico provider, ma non consente di definire regole di autorizzazione per singola applicazione. Con Traefik davanti, devi usare forward auth (single application). Se vuoi un'applicazione concreta su cui fare pratica, una soluzione come un workspace AFFiNE self-hosted è un buon primo candidato, perché è il tipo di strumento interno che vuoi rendere raggiungibile dai tuoi dispositivi e da nessun altro. Il caso è ancora più evidente con uno strumento di team: inserisci un help desk Chatwoot self-hosted dietro lo stesso provider, così chiunque risponda alla casella di posta effettua l'accesso una volta al giorno invece di condividere un'altra password.

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 che punti a quel provider. Poi apri Outposts, modifica authentik Embedded Outpost e aggiungi la nuova applicazione all'elenco delle applicazioni selezionate. L'outpost risponde soltanto per le applicazioni che gli sono state 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 inoltrata all'upstream. Se lo ometti, l'applicazione resta protetta, ma non sa quale utente ha effettuato l'accesso. Di conseguenza, qualsiasi componente che legge X-authentik-username per eseguire l'accesso automatico resta non autenticato. La differenza è evidente soprattutto davanti a un'applicazione che gestisce un proprio accesso, come un tracker di allenamento openGym self-hosted con accesso tramite passkey: gli header determinano se la stessa pagina richiede una sola autenticazione 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 è la parte che spesso viene omessa. Dopo l'accesso, Authentik reindirizza il browser a un percorso sotto /outpost.goauthentik.io/ sull'hostname dell'applicazione, non su auth.example.com. Se non esiste un router che inoltra quel prefisso di percorso al servizio Authentik, la richiesta raggiunge l'applicazione, che restituisce 404, e l'accesso non viene completato. Il valore priority più alto fa sì che la regola per il percorso specifico prevalga sulla regola Host() generica dello stesso dominio.

Esegui il test in una finestra privata del browser. 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.

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ù maturo, supportato da Red Hat, ed è la scelta più solida per gli scenari di identity management aziendale tradizionale: federazione SAML avanzata, brokeraggio degli accessi da più identity provider esterni contemporaneamente ed esportazione e importazione dei realm come percorso di migrazione documentato. Per alcune organizzazioni, anche il supporto commerciale disponibile è un elemento importante. Il compromesso è che Keycloak non include un proxy proprio. Per proteggere un'applicazione che non supporta OIDC (OpenID Connect) è quindi necessario eseguire un componente come oauth2-proxy insieme a Keycloak. Il proxy provider integrato di Authentik svolge già questa funzione ed è integrato nel prodotto. Per questo motivo, la maggior parte degli utenti che gestiscono autonomamente un insieme eterogeneo di applicazioni 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 provenire da quella precedente. Crea il dump del database prima del pull, non dopo.

FAQ

Authentik è gratuito da eseguire in self-hosting?

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 è necessaria alcuna licenza.

È necessario 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 alterna continuamente la pagina di accesso e l'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 su un'altra, quindi Authentik considera anonima ogni richiesta. Correggi l'host esterno, quindi elimina i cookie per entrambi gli hostname prima di eseguire nuovamente il test.

Quanta RAM richiede Authentik?

Il requisito minimo documentato è di 2 core CPU e 2 GB di RAM a luglio 2026; il valore comprende PostgreSQL, il server e il worker. Su un sistema con 2 GB, il worker è il primo processo che il kernel termina quando la memoria è sotto pressione. 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.