Tutti gli articoli

OAuth 2 con Authorization Code e PKCE, spiegato bene

«Accedi con Google», l'app che legge il tuo calendario, la CLI che si collega al cloud: dietro c'è quasi sempre OAuth 2. Vediamo come funziona davvero, chi fa cosa e perché PKCE è diventato obbligatorio. Poi lo eseguiamo dal vivo.

Pubblicato il 8 ottobre 2026 16 min di letturaOAuth 2PKCESicurezzaOpenID Connect
01

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

Alcune auto hanno una seconda chiave da dare al parcheggiatore: accende il motore ma non apre il bagagliaio e non supera i 20 km/h. Un access token è questo: una chiave ridotta, data a uno specifico servizio, per uno scopo preciso.

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.

02

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.

Mappa dei componentiInterattivo
usalogin su /authorize/tokenfederacookieBearerJWKSUtenteresource ownerBrowseruser-agentClientSPA · mobile · webBFFbackend for frontendIdP esternoGoogle · Entra · SPIDAuthorization ServerKeycloak · Auth0 · Entra ID/authorize/token/.well-known/jwks/userinfo/introspect/revokeAPI Gatewayverifica il tokenResource Serverla tua API
front-channel (passa dal browser) back-channel (server a server) componente opzionale

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.

  • /authorize Front-channel. Qui arriva il browser: login, consenso, poi redirect con il code.
  • /token Back-channel. Il client scambia code + code_verifier con i token. Anche il refresh passa da qui.
  • /.well-known Discovery (openid-configuration): un JSON con gli URL di tutti gli altri endpoint.
  • /jwks Le chiavi pubbliche con cui le API verificano la firma dei JWT.
  • /userinfo OpenID Connect: restituisce i dati del profilo dato un access token.
  • /introspect Le API chiedono «questo token è ancora valido?». Utile con token opachi.
  • /revoke Invalida un refresh o access token, per esempio al logout.
Clicca su un componente per vedere a cosa serve. I bordi tratteggiati indicano componenti opzionali ma molto comuni nelle architetture aziendali.

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.

03

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.

Authorization Code + PKCEAnimato
UtenteBrowserClientAuth ServerAPI1clic su «Accedi»2genera verifier + challenge3302 → /authorize4GET /authorize5pagina di login e consenso6credenziali + MFA + «Consenti»7302 → callback?code=…8GET /callback?code=…9POST /token (code + verifier)10200 { access_token, … }11GET /orders Bearer …12200 dati
passo 1 / 12 · locale

1. L'utente vuole entrare

Tutto parte da un'azione dell'utente: un pulsante «Accedi» o il tentativo di aprire una pagina protetta.

Clicca su una freccia o usa i pulsanti. Le frecce tratteggiate passano dal browser (front-channel), quelle piene sono chiamate dirette (back-channel).

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.

GrantQuandoOAuth 2.1
Authorization Code + PKCEUtente presente: web app, SPA, mobile, desktop, CLI✓ lo standard
Client CredentialsServer che parla con server, nessun utente✓
Device AuthorizationTV, console, dispositivi senza tastiera✓
Refresh TokenRinnovare un access token senza nuovo login✓
ImplicitVecchie SPA: token direttamente nell'URL✗ rimosso in OAuth 2.1
Resource Owner PasswordL'app chiede username e password✗ rimosso in OAuth 2.1
04

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:

Intercettare il codiceSimulazione

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.

Dal verifier al challengeInterattivo

code_verifier · resta nel client

dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

43 caratteri (da 43 a 128)

SHA-256 → base64url

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 valore iniziale è l'esempio ufficiale dell'RFC 7636. SHA-256 è una funzione a senso unico: dal challenge non si risale al verifier.

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

PKCE è nato per i client public, ma protegge anche i confidential da un altro attacco, l'authorization code injection. Per questo le best practice di sicurezza IETF (RFC 9700) e la bozza di OAuth 2.1 lo richiedono per tutti i client che usano Authorization Code. Usa sempre S256, mai il metodo plain.
05

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ì.

OAuth 2 playgroundDal vivo
authorization server

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.

1

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).

richiesta
GET https://demo.duendesoftware.com/.well-known/openid-configuration
2

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.

3

Manda l'utente all'authorization server

Questo è l'URL esatto a cui il browser viene rediretto. Ogni parametro ha un ruolo preciso:

4

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.

5

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.

richiesta
POST  HTTP/1.1
Content-Type: application/x-www-form-urlencoded

oppure da terminale
curl -X POST '' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
6

Guarda dentro i token

7

Usa l'access token

richiesta
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.

8

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.

richiesta
POST  HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=
&client_id=interactive.public
Le chiamate partono direttamente dal tuo browser verso l'authorization server: questo sito non vede né inoltra codici o token. I token del server demo sono di prova e scadono in un'ora.

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.

06

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 tokenRefresh tokenID token
Per chi èPer l'API (resource server)Per l'authorization serverPer il client
A cosa serveAutorizzare una chiamataOttenere nuovi access tokenSapere chi è l'utente
Formato tipicoJWT oppure opacoOpacoSempre JWT (OpenID Connect)
Durata tipica5–60 minutiOre, giorni o settimanePochi minuti (si legge subito)
Dove vaHeader Authorization: BearerSolo all'endpoint /tokenNon 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.

07

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.

08

In sintesi

  1. 1OAuth 2 serve a delegare un accesso limitato senza condividere la password. Per sapere chi è l'utente si aggiunge OpenID Connect.
  2. 2Gli attori sono utente, client, authorization server e resource server. Nella realtà si aggiungono browser, gateway, BFF e IdP esterni.
  3. 3Authorization Code divide il flusso in due: un codice inutile da solo nel front-channel, i token veri nel back-channel.
  4. 4PKCE lega il codice al client che ha iniziato il flusso: verifier segreto, challenge pubblico, SHA-256 in mezzo.
  5. 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.

GP

Lead | Solution Architect – CIAM & API Security

Fatto con da Gianni

© 2026 Tutti i diritti riservati

Costruito con Next.js & Tailwind CSS