Implementazione precisa del flusso OAuth2 Authorization Code con PKCE: guida passo-passo per evitare errori di token e contesti non validi in applicazioni web italiane

Esempio di scambio token POST:
POST /token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=RECEIVED_AUTHORIZATION_CODE&redirect_uri=https://your-app.it/auth/callback&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET

Nota critica: il client_secret deve essere gestito come credenziale protetta, mai esposto nel client JS. Il token di accesso ricevuto è un JWT con claim exp (scadenza), iat (issued at), aud (audience), e sub (subject). La sua validità deve essere verificata tramite firma HMAC-SHA256 con chiave segreta del provider.

Fase 4: Validazione avanzata del token lato backend
Un’implementazione rigida richiede la verifica multipla:
- Firma valida tramite chiave pubblica del provider (in OpenID Connect, iss, aud, nonce).
- Scadenza exp verificata con orologio sincronizzato (NTP).
- Verifica iat vs orario sistema per prevenire replay.
- Controllo jti per prevenire token duplicati.
- Revoca tramite Introspection endpoint (es. OpenID Connect Token Introspection) per token invalidati.

Esempio di validazione JWT con libreria PyJWT:
import jwt
from datetime import datetime, timezone

def validate_token(jwt_token, issuer, audience, public_key):
try:
decoded = jwt.decode(jwt_token, public_key, algorithms=["S256"], options={"require": ["exp", "iat", "aud"]})
now = datetime.now(timezone.utc)
if now > datetime.fromtimestamp(decoded['iat'], tz=timezone.utc) or now > datetime.fromtimestamp(decoded['exp'], tz=timezone.utc):
raise ValueError("Token scaduto")
if decoded['aud'] != audience:
raise ValueError("Token non destinato a questa applicazione")
return True
except jwt.ExpiredSignatureError:
return False, "Token scaduto"
except jwt.InvalidIssuerError:
return False, "Emittente non valido"
except jwt.InvalidTokenError:
return False, "Token non valido"

Fase 5: Gestione avanzata del refresh token e cicli di rinnovo
Il refresh token, se emesso, deve essere trattato come un asset critico: ciclo automatico di rinnovo ogni 24-48 ore prima della scadenza, con backup su database crittografato e logging di ogni rinnovo.

Esempio: refresh token con rinnovo automatico:
async def refresh_access_token(refresh_token, client_id, client_secret, provider_url):
data = {
"grant_type": "refresh_token",
"refresh_token": refresh_token,
"client_id": client_id,
"client_secret": client_secret,
}
async with aiohttp.ClientSession() as session:
async with session.post(f"{provider_url}/token", data=data) as resp:
if resp.status == 200:
return await resp.json()
else:
raise RuntimeError("Rinnovo refresh token fallito: " + await resp.text())

L’refresh_token deve essere trattato con HttpOnly Cookie o Secure Session Store, mai in local storage.

Errori comuni da evitare e troubleshooting pratico
- Token scaduto o mancante claim exp: controlla sempre iat e exp con orologio sincronizzato.
- Redirect URI mismatch: verifica assoluta corrispondenza tra URI registrati e reindirizzati; un errore qui blocca l’autenticazione.
- Challenge/verifier mancante o errato: assicurati che la libreria generi e verifichi correttamente il challenge HMAC.
- Revoca non propagata: usa OpenID Connect Introspection per sincronizzare revoca in tempo reale.
- Token revocati ma ancora usati