Integrazione SSO Authentik: guida per lo sviluppo con LLM e senza

Scopo e principi

Ogni progetto interno si integra con l'SSO aziendale in un solo modo: OIDC standard verso Authentik, con una libreria mantenuta e zero configurazioni speciali. Questa guida spiega le regole e fornisce il prompt da dare all'LLM (Claude, Copilot, Cursor, ecc.) quando gli si chiede di implementare il login.

Il principio guida è KISS. Ogni regola custom su Authentik (flow, property mapping, policy, scope dedicati) va gestita e mantenuta dal DevOps per sempre, e crea un progetto "snowflake" diverso da tutti gli altri. Se un'integrazione sembra richiedere qualcosa di particolare, il problema va risolto nell'applicazione, non in Authentik.

Per la configurazione di Authentik in sé, l'LLM deve basarsi solo sulla documentazione ufficiale di Authentik, non su tutorial di terzi o sulla propria memoria.

Regole fisse

Queste regole non si discutono progetto per progetto. Un'eccezione richiede un'approvazione esplicita del DevOps, motivata nel ticket.

Tema	Regola
Protocollo	Solo OpenID Connect (Authorization Code flow). Niente SAML, LDAP, proxy/forward auth o OAuth2 "puro".
Identity provider	`https://login.eagleprojects.cloud`. L'issuer è per applicazione: `https://login.eagleprojects.cloud/application/o/<slug>/` (con lo slash finale).
Configurazione endpoint	Solo tramite discovery (`<issuer>.well-known/openid-configuration`). Mai URL di authorize, token o userinfo scritti a mano.
Tipo di client	Sempre confidential, con `client_secret`. Il flusso OIDC gira sempre lato backend, anche per le SPA.
Provider per progetto	Un'unica Application/Provider per progetto, condivisa da tutti gli ambienti. I redirect URI di ogni ambiente (localhost compreso, se serve) stanno sullo stesso provider.
Scope	`openid profile email`. Nessuno scope custom.
Autorizzazione	Ruoli derivati dal claim `groups` del token. L'app non gestisce utenti o password propri.
Libreria	Una libreria OIDC certificata o diffusa e mantenuta per lo stack in uso. Vietato implementare il protocollo a mano.
Secret	In un file `.env` non versionato oppure in OpenBao. Mai nel codice, nei log o nel repository.

Il claim groups arriva con lo scope standard profile, grazie al mapping di default di Authentik. Se in un progetto non arriva, va segnalato nel ticket: non si aggiungono scope o mapping custom lato applicazione.

Processo: richiesta al DevOps

Nessuno sviluppatore e nessun LLM crea o modifica Application, Provider o gruppi su Authentik. Si apre un ticket su cloud-support.eagleprojects.cloud e il DevOps fa la configurazione standard.

Nel ticket indicare:

Nome del progetto e slug proposto (minuscolo, con trattini, es. gestione-commesse).
Redirect URI di ogni ambiente, es. https://gestione-commesse.eagleprojects.cloud/auth/callback e, se serve, http://localhost:3000/auth/callback.
URI di post-logout, se l'app fa logout anche su Authentik.
Gruppi necessari, secondo la convenzione sotto, e quali di questi possono accedere all'app.
Referente del progetto.

Il DevOps restituisce:

client_id e client_secret, consegnati tramite OpenBao o canale sicuro (mai via ticket in chiaro).
L'issuer del provider, da copiare così com'è.
Conferma dei gruppi creati e della restrizione di accesso.

Per aggiungere un ambiente o un redirect URI si apre un nuovo ticket sullo stesso provider, non se ne crea uno nuovo.

Configurazione standard

Ogni progetto legge la configurazione OIDC dalle stesse variabili d'ambiente, con gli stessi nomi. Cambiare ambiente significa cambiare solo OIDC_REDIRECT_URI e l'URL dell'app.

OIDC_ISSUER=https://login.eagleprojects.cloud/application/o/<slug>/
OIDC_CLIENT_ID=<dal DevOps>
OIDC_CLIENT_SECRET=<da OpenBao o .env>
OIDC_REDIRECT_URI=https://<app>/auth/callback
OIDC_POST_LOGOUT_REDIRECT_URI=https://<app>/
OIDC_SCOPES=openid profile email
SESSION_SECRET=<stringa casuale lunga>

Nel repository va un .env.example con questi nomi e valori segnaposto; il .env reale è in .gitignore.

Rotte applicative

Rotta	Funzione
`/auth/login`	Avvia il flusso verso Authentik (con `state`, `nonce` e PKCE gestiti dalla libreria).
`/auth/callback`	Riceve il code, lo scambia con i token, valida l'ID token e crea la sessione.
`/auth/logout`	Distrugge la sessione locale e, se previsto, reindirizza all'`end_session_endpoint` letto dal discovery.
`/auth/me`	Restituisce utente e gruppi della sessione corrente (utile alle SPA).

Convenzione per i gruppi

I gruppi sono per applicazione e seguono lo schema <slug>-<ruolo>, es. gestione-commesse-admin e gestione-commesse-user. Partire con due ruoli e aggiungerne solo quando servono davvero.

L'app mappa i gruppi ai propri ruoli in un unico punto del codice (una funzione o un file di configurazione), leggendo il claim groups a ogni login. I ruoli non vanno salvati in modo permanente nel database dell'app: Authentik è l'unica fonte di verità.

Architettura con SPA

Anche quando il frontend è una SPA separata, il backend fa da BFF (backend for frontend): gestisce tutto il flusso OIDC e il browser riceve solo un cookie di sessione. Così i token non sono mai esposti a JavaScript e c'è un solo modello di integrazione per tutti i progetti.

[embedded content: flusso di login con SPA · backend come BFF]

La SPA chiama /auth/me per sapere chi è l'utente e quali gruppi ha; ogni API controlla sessione e ruoli lato server. Servire SPA e backend sotto lo stesso dominio (es. /api dietro lo stesso reverse proxy) evita problemi di CORS e di cookie cross-site.

Prompt template per l'LLM

Copiare il blocco sotto all'inizio della richiesta all'LLM, oppure nel file di istruzioni del progetto (AGENTS.md, CLAUDE.md, .github/copilot-instructions.md). Sostituire solo i valori tra parentesi angolari.

Devi integrare questa applicazione con il nostro SSO aziendale (Authentik).
Segui queste regole senza eccezioni. Se una regola sembra impedirti di
procedere, fermati e chiedimi invece di inventare un'alternativa.

CONTESTO
- Stack del progetto: <es. Node.js + Express + React>
- Slug dell'applicazione su Authentik: <slug>
- URL dell'app: <https://...> (in locale: <http://localhost:PORT>)

REGOLE
1. Protocollo: solo OpenID Connect, Authorization Code flow con PKCE.
   Niente SAML, LDAP, proxy/forward auth, implicit flow.
2. Identity provider: issuer letto da OIDC_ISSUER, nella forma
   https://login.eagleprojects.cloud/application/o/<slug>/
   Tutti gli endpoint vanno ricavati dal discovery
   (<issuer>.well-known/openid-configuration). Mai URL scritti a mano.
3. Client confidential con client_secret. Il flusso OIDC gira SOLO nel
   backend. Il frontend non vede mai token: usa una sessione con cookie
   HttpOnly, Secure, SameSite=Lax.
4. Usa una libreria OIDC standard e mantenuta per lo stack (indicami
   quale scegli e perché). Non implementare il protocollo a mano.
5. Scope: "openid profile email". Nessuno scope custom.
6. Configurazione solo da variabili d'ambiente con questi nomi:
   OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, OIDC_REDIRECT_URI,
   OIDC_POST_LOGOUT_REDIRECT_URI, OIDC_SCOPES, SESSION_SECRET.
   Crea un .env.example con valori segnaposto e verifica che .env sia
   in .gitignore. Mai secret nel codice o nei log.
7. Rotte: /auth/login, /auth/callback, /auth/logout, /auth/me.
8. Autorizzazione: ruoli derivati dal claim "groups" a ogni login.
   Gruppi nel formato <slug>-<ruolo> (es. <slug>-admin, <slug>-user).
   Mappatura gruppi -> ruoli in un unico punto del codice.
   Nessuna gestione locale di utenti, password o ruoli persistenti a meno che non sia strettamente necessario.
9. Valida l'ID token (firma, issuer, audience, scadenza, nonce):
   delegalo alla libreria, non disabilitare mai i controlli.
10. Non toccare la configurazione di Authentik. Se serve qualcosa lato
    Authentik, scrivimi il testo del ticket per il DevOps.

RIFERIMENTI
- Per Authentik usa solo la documentazione ufficiale:
  https://docs.goauthentik.io/docs/providers/oauth2/
- Non seguire tutorial di terzi che aggiungono scope mapping, flow o
  policy custom.

OUTPUT ATTESO
- Il codice dell'integrazione.
- Il .env.example.
- L'elenco dei redirect URI da chiedere al DevOps.
- Una breve nota su come testare il login in locale.

Checklist di revisione

Prima del merge, chi revisiona il codice generato verifica questi punti.

Endpoint letti dal discovery, nessun URL di Authentik scritto a mano oltre all'issuer.
Libreria OIDC standard, nessuna implementazione manuale di token o firme.
Token solo nel backend; il browser riceve un cookie di sessione HttpOnly e Secure.
Validazione dell'ID token attiva (firma, issuer, audience, scadenza, nonce).
Variabili d'ambiente con i nomi standard, .env.example presente, .env ignorato da git.
Ruoli calcolati dal claim groups in un unico punto del codice.
Nessuna tabella utenti con password o ruoli persistenti.
Nessuna richiesta di scope, mapping, flow o policy custom su Authentik.

Segnali di uno snowflake

Se l'LLM propone una di queste cose, la risposta è no: va riformulata la richiesta o aperto un ticket per discuterne.

Creare un "groups" scope mapping custom o modificare i flow di Authentik.
Usare il proxy provider o il forward auth perché "è più semplice".
Salvare access token o refresh token nel localStorage del browser.
Creare un provider separato per ogni ambiente.
Disabilitare la verifica dell'issuer o del certificato "per farlo funzionare in locale".

Fonti

Authentik, OAuth2/OpenID provider