Keycloak: cos'è e perché dovresti usarlo per la tua web app

Se hai mai scritto un sistema di login da zero - registrazione, reset password, gestione sessioni, hash delle credenziali - sai quanto tempo porta via. E sai anche che, per quanto lo testi, resta quella sensazione fastidiosa: stai davvero gestendo le password in modo sicuro?

Poi arriva il secondo progetto e magari ti ritrovi a scrivere tutto da capo. Stesse tabelle, stessa logica e, ovviamente, gli stessi dubbi ma con password duplicate in più punti, e magari diverse.

C’è un modo migliore: delegare tutto a un Identity Provider. In questo articolo vediamo cos’è, come funziona, e perché Keycloak merita un posto nel tuo stack.

Il problema: i silos di identità

Immagina di avere tre applicazioni nella tua organizzazione: un’app HR, un CRM e un client email. Ognuna gestisce le proprie credenziali in modo indipendente.

I problemi di questo modello sono noti:

• Password duplicate: l’utente usa la stessa password ovunque, o ne dimentica alcune
• Nessun Single Sign-On: login separato per ogni applicazione
• Gestione frammentata: quando un dipendente lascia l’azienda, devi disabilitarlo su N sistemi diversi
• Sicurezza inconsistente: ogni app implementa (o non implementa) MFA, lockout, audit a modo suo

E le architetture moderne non aiutano. Oggi un progetto può avere una SPA (Single Page App), un’API REST, cinque microservizi e un’app mobile. Ognuno di questi deve sapere chi sta chiamando. Riscrivere la logica di autenticazione in ognuno? Insostenibile.

La soluzione: un Identity Provider centralizzato

L’idea è semplice: togli l’autenticazione dalle tue applicazioni e la centralizzi in un componente dedicato. Le app non gestiscono più credenziali ma ricevono token firmati dall’Identity Provider e li validano.

In pratica, l’utente fa login una sola volta sull’IdP e, da quel momento, tutte le applicazioni collegate ricevono un token che conferma chi è e cosa può fare. È il principio del Single Sign-On (SSO).

Le tue applicazioni non toccano più le credenziali: si limitano a verificare che il token sia valido e firmato dall’IdP. Se il tuo codice non gestisce password, non può gestirle male. Un dipendente lascia l’azienda? Lo disabiliti in un punto solo e perde accesso a tutto.

Qui entra in gioco Keycloak

Keycloak è un Identity Provider open source, nato in casa Red Hat e rilasciato con licenza Apache 2.0. Non è un framework da integrare nel tuo codice ma un servizio a sé stante. Lo avvii, lo configuri, e lui si occupa di autenticazione, autorizzazione e gestione utenti.

Cosa ti offre, in concreto:

• Authorization Server: implementa OAuth 2.0 e OpenID Connect, quindi supporta tutti i flussi di autenticazione standard. Non devi reinventare la ruota: le tue app delegano l’autenticazione a Keycloak seguendo standard aperti.
• User Federation: hai già un LDAP o Active Directory con migliaia di utenti? Keycloak si collega e li usa senza migrazione.
• Social Login: login con Google, GitHub, Facebook. Configurabile dall’admin console.
• Single Sign-On: un login per tutte le tue app. Logout da una, logout da tutte.
• Admin Console: un’interfaccia web completa per gestire utenti, ruoli, client e configurazioni. Niente SQL a mano.

💡 Keycloak è container-ready: puoi avviarlo con Docker in un minuto. Ha anche un Kubernetes Operator ufficiale per ambienti di produzione.

I concetti chiave

Prima di toccare il codice vediamo quattro concetti da conoscere:

• Realm: il contenitore principale, una specie di “tenant”. Ogni realm ha i propri utenti, ruoli e configurazioni, isolati dagli altri.
• Client: ogni applicazione che si collega a Keycloak. Il tuo frontend React è un client, la tua API Express è un altro.
• User: gli utenti del tuo sistema. Keycloak gestisce registrazione, credenziali, profili e sessioni al posto tuo.
• Role: i permessi. Li definisci tu in base a quello che serve al tuo progetto. Finiscono nel token JWT e la tua app li usa per decidere cosa mostrare.

Facciamo un esempio. Crei il realm techstore, registri due client (shop-ui e shop-api), aggiungi gli utenti Mario e Admin. Assegni il ruolo admin solo al secondo. Quando Mario fa login, il suo token dice alla tua app esattamente cosa può fare e cosa no.

Come funziona il login

Il flusso standard per una web app si chiama Authorization Code Flow. Sembra complesso, ma dal punto di vista dell’utente sono tre passaggi:

1. L’utente clicca “Login” nella tua app → viene reindirizzato alla pagina di login di Keycloak
2. L’utente inserisce le credenziali su Keycloak (non sulla tua app!)
3. Keycloak reindirizza l’utente alla tua app con un codice di autorizzazione, che la libreria client scambia automaticamente con i token JWT

La tua applicazione non tocca mai le credenziali. Riceve un JWT (JSON Web Token) che contiene chi è l’utente, i suoi ruoli e una scadenza. Keycloak lo firma con la propria chiave privata; la tua app lo valida scaricando la chiave pubblica corrispondente. Se qualcuno modifica il token, la firma non corrisponde più e viene rifiutato.

In realtà Keycloak non rilascia un solo token ma due. L’access token ha vita breve — 5 minuti di default — e viene inviato dal frontend al backend a ogni richiesta API per dimostrare chi è l’utente. Quando scade, l’utente non deve rifare il login: entra in gioco il secondo token: il refresh token, dotato di una vita più lunga (30 minuti di default), che la tua app usa dietro le quinte per chiedere a Keycloak un nuovo access token. A ogni rinnovo, Keycloak rilascia anche un nuovo refresh token, quindi il ciclo si ripete in modo trasparente finché l’utente è attivo. Se resta inattivo troppo a lungo e il refresh token scade, dovrà autenticarsi di nuovo.

⚠️ La tua app non deve avere un form di login proprio. Se raccogli username e password nel tuo frontend, le credenziali passano attraverso il tuo codice e torni al punto di partenza: devi proteggerle, trasmetterle in modo sicuro e gestire i casi d’errore. Il redirect a Keycloak esiste proprio per evitarlo.

Provarlo in un minuto

Vuoi vedere Keycloak in azione? Un comando Docker e sei operativo/a:

docker run -p 8080:8080 \
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
  -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:26.2 start-dev

Apri http://localhost:8080, accedi con admin/admin, e hai la console di amministrazione davanti. Da lì puoi creare un realm, aggiungere utenti e configurare il tuo primo client.

Lato Keycloak, per un primo login funzionante bastano pochi passi dall’interfaccia web: crea un realm, aggiungi un client di tipo “public” con il redirect URI della tua app, e crea un utente. Lato applicazione, dovrai integrare una libreria client, come keycloak-js per il frontend o un middleware JWT per il backend, ma la logica di autenticazione vera e propria resta tutta su Keycloak.

⚠️ start-dev avvia Keycloak in modalità sviluppo. Non usarlo in produzione: abilita HTTP senza TLS, usa un database H2 locale non adatto a carichi reali e rilassa diverse configurazioni di sicurezza.

Errori comuni da evitare

Quando cominci con Keycloak, queste sono le trappole più frequenti in cui è facile cadere:

• Form di login nella tua app: se raccogli username e password nel tuo frontend, stai bypassando il senso di un IdP. Usa sempre il redirect a Keycloak.
• start-dev in produzione: start-dev usa HTTP e un database H2 in memoria. Token e credenziali viaggiano in chiaro e i dati non sopravvivono a un riavvio. In produzione serve start con PostgreSQL e HTTPS.
• Hardcodare URL: l’URL di Keycloak cambia tra locale, staging e produzione. Rendilo configurabile fin dal primo giorno, sia nel backend che nel frontend. Altrimenti il primo deploy fuori da localhost ti accoglie con un 401 inspiegabile.

Conclusione

Keycloak non è “un’altra cosa da imparare”: è una cosa in meno da scrivere. Login, registrazione, reset password, SSO, MFA, gestione utenti, etc… tutto gestito da un componente dedicato, testato, e mantenuto da una community attiva.

Se la tua applicazione ha utenti, ha bisogno di autenticazione. E l’autenticazione è troppo critica per reinventarla ogni volta.

Risorse utili:

• Keycloak Documentation - il punto di partenza ufficiale
• Keycloak Getting Started Guide - primo setup con Docker
• OAuth 2.0 Simplified - guida accessibile a OAuth 2.0
• OpenID Connect Specification - lo standard dietro il login delegato