Il problema: dare accesso senza dare la password
Immagina un'app che deve leggere le tue foto su un servizio di cloud. Il modo più ingenuo è chiederti username e password e usarli al posto tuo. Funziona, ma è un disastro: l'app può fare tutto quello che puoi fare tu, per sempre, e l'unico modo per fermarla è cambiare password. Se l'app viene bucata, la tua password è nelle mani di qualcun altro.
OAuth 2 (RFC 6749) risolve questo problema con un'idea semplice: invece della password, l'app riceve un token, una specie di pass temporaneo che vale solo per certe operazioni (gli scope), solo per un certo tempo e che può essere revocato in qualunque momento senza toccare la tua password.
L'analogia della chiave da parcheggiatore
Attenzione a una distinzione che confonde molti: OAuth è un protocollo di autorizzazione (cosa può fare l'app), non di autenticazione (chi è l'utente). Per sapere chi ha fatto login si usa OpenID Connect, uno strato sottile sopra OAuth che aggiunge l'id_token, lo scope openid e l'endpoint /userinfo. Nella pratica si usano quasi sempre insieme.
Gli attori e i componenti architetturali
La specifica definisce quattro ruoli: resource owner (l'utente), client (l'app), authorization server (chi emette i token) e resource server (l'API). In un'architettura reale se ne aggiungono altri: il browser che fa da tramite, un API gateway, a volte un backend dedicato alla SPA, spesso un identity provider esterno.
Authorization server
Authorization Server
Il cuore del sistema. Autentica l'utente, raccoglie il consenso e emette i token. Espone una serie di endpoint standard, che un client scopre leggendo il documento di discovery.
Esempi: Keycloak, Auth0, Okta, Microsoft Entra ID, AWS Cognito, Duende IdentityServer.
Occhio a: Registra redirect_uri esatti (niente wildcard), richiedi PKCE, tieni brevi gli access token.
/authorizeFront-channel. Qui arriva il browser: login, consenso, poi redirect con il code./tokenBack-channel. Il client scambia code + code_verifier con i token. Anche il refresh passa da qui./.well-knownDiscovery (openid-configuration): un JSON con gli URL di tutti gli altri endpoint./jwksLe chiavi pubbliche con cui le API verificano la firma dei JWT./userinfoOpenID Connect: restituisce i dati del profilo dato un access token./introspectLe API chiedono «questo token è ancora valido?». Utile con token opachi./revokeInvalida un refresh o access token, per esempio al logout.
Il concetto chiave da portarsi a casa è la differenza tra i due canali. Il front-channel passa dal browser tramite redirect: è comodo perché coinvolge l'utente, ma tutto ciò che vi transita è esposto (cronologia, log dei proxy, estensioni, header Referer). Il back-channel è una chiamata HTTP diretta tra client e server: nessuno nel mezzo. Tutto il design di OAuth ruota attorno a una regola: nel front-channel passano solo cose che, da sole, non valgono niente.
Client public e client confidential
Un client confidential gira su un server e può custodire un segreto (client_secret, o meglio una chiave privata). Un client public gira sul dispositivo dell'utente: una SPA, un'app mobile, una CLI. Qualunque segreto incluso nel codice può essere estratto, quindi è come non averlo. Questa differenza è il motivo per cui esiste PKCE.
Il flusso Authorization Code, passo per passo
OAuth prevede diversi modi per ottenere un token, chiamati grant. Quello che si usa ogni volta che c'è un utente davanti a uno schermo è l'Authorization Code. L'idea è dividere il lavoro in due: prima, nel front-channel, l'utente ottiene un codice temporaneo; poi, nel back-channel, il client scambia quel codice con i token veri.
1. L'utente vuole entrare
Tutto parte da un'azione dell'utente: un pulsante «Accedi» o il tentativo di aprire una pagina protetta.
Perché non restituire subito il token al passo 7, invece di un codice? È esattamente quello che faceva il vecchio flusso Implicit, ed è il motivo per cui è stato abbandonato: un token nell'URL finisce nella cronologia, nei log e nelle mani di chiunque riesca a leggere quell'indirizzo. Un codice invece è monouso, scade in pochi secondi e, con PKCE, è inutilizzabile da chiunque non abbia anche il verifier.
| Grant | Quando | OAuth 2.1 |
|---|---|---|
| Authorization Code + PKCE | Utente presente: web app, SPA, mobile, desktop, CLI | ✓ lo standard |
| Client Credentials | Server che parla con server, nessun utente | ✓ |
| Device Authorization | TV, console, dispositivi senza tastiera | ✓ |
| Refresh Token | Rinnovare un access token senza nuovo login | ✓ |
| Implicit | Vecchie SPA: token direttamente nell'URL | ✗ rimosso in OAuth 2.1 |
| Resource Owner Password | L'app chiede username e password | ✗ rimosso in OAuth 2.1 |
Perché serve PKCE
Nel flusso base c'è un buco. Il codice torna al client passando dal browser, e per un client confidential non è un problema: per usarlo serve anche il client_secret, che l'attaccante non ha. Ma un client public non ha segreti. Chi intercetta il codice può scambiarlo al posto suo.
Non è teoria. Sui telefoni più app possono registrare lo stesso schema di URL (com.banca.app://) e il sistema operativo consegna il redirect a una di loro. Prova l'attacco:
App legittima
Auth Server
App malevola
L'app legittima avvia il login. Sul telefono è installata anche un'app malevola che ha registrato lo stesso schema di redirect (com.banca.app://callback).
PKCE (Proof Key for Code Exchange, RFC 7636, si pronuncia «pixie») è un segreto usa-e-getta creato al volo per ogni login. Il client genera un valore casuale, il code_verifier, e all'inizio del flusso manda solo il suo hash, il code_challenge. Alla fine, per riscattare il codice, deve presentare il verifier originale. L'authorization server ne calcola l'hash e controlla che corrisponda.
code_verifier · resta nel client
dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
43 caratteri (da 43 a 128)
sola andata
code_challenge · viaggia nell'URL
code_challenge_method=S256
Mettiti nei panni dell'attaccante: hai visto il challenge passare nell'URL. Riesci a trovare un verifier che produca lo stesso hash?
Il trucco funziona perché le due metà del segreto viaggiano su canali diversi: il challenge nel front-channel (esposto, ma inutile), il verifier nel back-channel (prezioso, ma protetto da TLS). Per rubare il token un attaccante dovrebbe intercettare entrambi.
Non solo per le app mobile
S256, mai il metodo plain.Guida interattiva: le chiamate vere
Basta teoria. Qui sotto esegui il flusso completo contro un authorization server pubblico, demo.duendesoftware.com, un server di test aperto a tutti. Ogni passo mostra la richiesta esatta che parte dal tuo browser e la risposta che torna. Puoi anche inserire i parametri del tuo server (Keycloak, Auth0, Entra ID…) e ripetere tutto lì.
demo.duendesoftware.com è un authorization server pubblico mantenuto da Duende per i test. Il client interactive.public è un client public con PKCE obbligatorio. Utenti di prova: bob / bob oppure alice / alice.
Scopri gli endpoint (discovery)
Un client non deve conoscere a memoria gli URL: li legge da un documento JSON pubblico, sempre allo stesso indirizzo. È OpenID Connect Discovery (per OAuth puro esiste l'equivalente RFC 8414).
GET https://demo.duendesoftware.com/.well-known/openid-configuration
Genera code_verifier, code_challenge e state
Generati qui, nel tuo browser, con crypto.getRandomValues e crypto.subtle.digest. Il verifier non lascerà questa pagina fino al passo 5.
Manda l'utente all'authorization server
Questo è l'URL esatto a cui il browser viene rediretto. Ogni parametro ha un ruolo preciso:
Ricevi il codice sul redirect_uri
Il codice da solo non serve a niente: ha bisogno del verifier. È per questo che può passare tranquillamente dalla barra degli indirizzi. Hai circa un minuto prima che scada, ed è monouso.
Scambia il codice con i token
Back-channel: una POST diretta all'endpoint /token. Nota l'assenza di client_secret (siamo un client public) e la presenza del code_verifier.
POST HTTP/1.1 Content-Type: application/x-www-form-urlencoded
curl -X POST '' \ -H 'Content-Type: application/x-www-form-urlencoded' \
Guarda dentro i token
Usa l'access token
GET https://demo.duendesoftware.com/api/test HTTP/1.1 Authorization: Bearer
/api/test del server demo restituisce i claim che ha letto dal tuo token: è la vista del resource server.
Rinnova con il refresh token
Quando l'access token scade, il client non rimanda l'utente al login: usa il refresh token (lo ottieni chiedendo lo scope offline_access). Il server demo applica la rotation: ogni refresh token si usa una volta sola e ne arriva uno nuovo.
POST HTTP/1.1 Content-Type: application/x-www-form-urlencoded grant_type=refresh_token &refresh_token= &client_id=interactive.public
Un paio di esperimenti che vale la pena fare: prova a premere due volte «Invia la richiesta» al passo 5 (il codice è monouso, la seconda volta ricevi invalid_grant), oppure rigenera il verifier dopo aver ottenuto il codice e ripeti lo scambio: l'authorization server rifiuterà la richiesta, perché il nuovo verifier non corrisponde al challenge inviato all'inizio.
Access, refresh e ID token
Alla fine del flusso arrivano fino a tre token diversi, ognuno con un destinatario preciso. Confonderli è una delle fonti di bug di sicurezza più comuni.
| Access token | Refresh token | ID token | |
|---|---|---|---|
| Per chi è | Per l'API (resource server) | Per l'authorization server | Per il client |
| A cosa serve | Autorizzare una chiamata | Ottenere nuovi access token | Sapere chi è l'utente |
| Formato tipico | JWT oppure opaco | Opaco | Sempre JWT (OpenID Connect) |
| Durata tipica | 5–60 minuti | Ore, giorni o settimane | Pochi minuti (si legge subito) |
| Dove va | Header Authorization: Bearer | Solo all'endpoint /token | Non va mandato alle API |
Molti access token sono JWT (JSON Web Token): tre parti in base64url separate da punti. Header (algoritmo e id della chiave), payload (i claim: chi l'ha emesso, per chi, fino a quando, con quali permessi) e firma. Chiunque può leggere un JWT, non è cifrato: la firma serve solo a garantire che nessuno l'abbia modificato. Quindi niente dati sensibili dentro.
Un'API che riceve un JWT lo verifica da sola, senza chiamare nessuno: scarica una volta le chiavi pubbliche dal jwks_uri, controlla la firma e poi iss, aud, exp e gli scope. Il prezzo di questa comodità è che un JWT non si può revocare prima della scadenza: ecco perché gli access token durano poco e il refresh token, che invece passa sempre dall'authorization server, può essere revocato.
Errori comuni e buone pratiche
Usare OAuth come «login»
OAuth dice cosa un'app può fare, non chi è l'utente. Per l'autenticazione usa OpenID Connect e l'ID token, non un access token qualsiasi.
redirect_uri con wildcard o confronti parziali
Se il server accetta https://app.example.com/*, un open redirect su una pagina qualsiasi diventa un modo per rubare codici. Confronto esatto, sempre.
Ignorare lo state (o il nonce)
Senza state un attaccante può farti completare il login con il suo account (login CSRF). Con PKCE il rischio cala, ma lo state resta raccomandato.
Token in localStorage
Qualunque script iniettato (XSS) li legge. Meglio tenerli in memoria, o meglio ancora usare un BFF e lasciare al browser solo un cookie HttpOnly.
Access token lunghi e scope larghi
Un token rubato vale finché non scade. Durate brevi, scope minimi, audience precisa: il danno resta piccolo.
API che non controllano aud
Un token emesso per l'API A non deve essere accettato dall'API B, anche se la firma è valida e viene dallo stesso server.
client_secret nel frontend
Un segreto in una SPA o in un'app mobile non è un segreto. Registra il client come public e affidati a PKCE.
E per le SPA?
Una single-page application può fare tutto da sola con Authorization Code + PKCE, come nel playground. Ma i token restano nel browser, raggiungibili da un eventuale XSS. Per applicazioni con dati sensibili il documento IETF «OAuth 2.0 for Browser-Based Applications» raccomanda il pattern BFF: un piccolo backend fa da client confidential, tiene i token lato server e al browser lascia solo un cookie HttpOnly; Secure; SameSite. Il JavaScript non vede mai un token.
In sintesi
- 1OAuth 2 serve a delegare un accesso limitato senza condividere la password. Per sapere chi è l'utente si aggiunge OpenID Connect.
- 2Gli attori sono utente, client, authorization server e resource server. Nella realtà si aggiungono browser, gateway, BFF e IdP esterni.
- 3Authorization Code divide il flusso in due: un codice inutile da solo nel front-channel, i token veri nel back-channel.
- 4PKCE lega il codice al client che ha iniziato il flusso: verifier segreto, challenge pubblico, SHA-256 in mezzo.
- 5Oggi la regola è semplice: Authorization Code + PKCE per tutto ciò che ha un utente, Client Credentials per server-to-server. Implicit e Password sono storia.
Per approfondire: RFC 6749 (OAuth 2.0), RFC 7636 (PKCE), RFC 9700 (OAuth 2.0 Security Best Current Practice), la bozza OAuth 2.1 e OpenID Connect Core 1.0.