Ciclo di vita del token in pratica

Ogni guida ai flussi OAuth cita refresh_token, ma un’integrazione di lunga durata (che continua a girare per molte richieste, worker o giorni) richiede più che “sostituire il token alla scadenza”. Questa pagina copre le durate reali dei token, come mettere in cache un token tra più worker, quando rinnovarlo e cosa può invalidare un token prima che scadrebbe naturalmente.

---

Durata dei token per flusso

La durata del token di accesso è un’unica durata fissa, uguale per ogni flusso. Quella del token di rinnovo no: dipende da quale flusso OAuth lo ha emesso.

Flusso	TTL del token di accesso	TTL del token di rinnovo
Flusso Client Credentials	Circa 1 ora	Circa 30 giorni
Flusso Native Application (PKCE, redirect loopback)	Circa 1 ora	Nessuna scadenza fissa: resta valido finché non viene sostituito dalla rotazione o revocato
Flusso Authorization Code + redirect personalizzato	Circa 1 ora	Nessuna scadenza fissa: resta valido finché non viene sostituito dalla rotazione o revocato

Nota

Entrambi i flussi Authorization Code emettono un token di rinnovo senza alcun orologio di sessione. Non resta comunque inutilizzato all’infinito: è un token monouso, sostituito a ogni rinnovo (vedi Race condition nei rinnovi concorrenti più sotto), e smette di funzionare immediatamente se la grant viene revocata.

Metti in cache il token, non generarne uno per richiesta

Richiedere un nuovo token di accesso a ogni chiamata API, o in modo indipendente in ogni processo worker, funziona ma spreca un round trip a ogni singola richiesta per un token già valido per circa un’ora. Richiedi un token, mettilo in cache (in memoria per un singolo processo, oppure in uno store condiviso come Redis per una flotta di worker) usando come chiave la credenziale che lo ha emesso, e passa il token in cache a ogni richiesta finché non è prossimo alla scadenza.

Questo vale anche per il token di rinnovo: meno processi lo scambiano in modo indipendente, meno probabile è incorrere nella race condition descritta di seguito.

Rinnova alla scadenza, non solo su un 401

Poiché la TTL del token di accesso è fissa e nota in anticipo, rinnova in modo proattivo: tieni traccia di quando hai ottenuto il token (o decodifica il suo claim exp) e richiedine uno nuovo poco prima di quel momento, invece di aspettare che una richiesta fallisca per prima.

Gestisci comunque una richiesta fallita come ripiego, ma distingui in base all’errore ricevuto:

• 401 con not_authenticated: la richiesta non conteneva alcun token bearer utilizzabile. È un bug lato client (header Authorization mancante o malformato), non un segnale per rinnovare.
• 401 con invalid_token: il controllo della firma o della scadenza del token è fallito. Rinnova e riprova una volta.
• 403: mai un problema di token. Il token è valido; chi chiama non ha lo scope, l’accesso al contenuto o il ruolo richiesti dall’operazione. Rinnovare non aiuterà. Consulta Codici di errore: Limitazione di frequenza, autenticazione e controllo degli accessi per il dettaglio completo di ogni codice.

Race condition nei rinnovi concorrenti

Un token di rinnovo è monouso: scambiarlo con grant_type=refresh_token invalida quel token di rinnovo ed emette insieme un nuovo token di accesso e un nuovo token di rinnovo. Se più worker condividono lo stesso token di rinnovo in cache e due di essi provano a rinnovare quasi nello stesso momento, solo uno scambio va a buon fine; l’altro riceve un 401 generico, non un errore distinguibile di “già utilizzato”.

Attenzione

Non lasciare che ogni worker rinnovi in modo indipendente contro un token di rinnovo condiviso. Designa un unico responsabile per la chiamata di rinnovo (un lock attorno al percorso di rinnovo, o una routine dedicata) e fai leggere agli altri worker il token di accesso risultante dalla cache condivisa, invece di rinnovare autonomamente.

Cosa invalida un token in anticipo

Nessuno degli eventi seguenti revoca direttamente un token di accesso ancora valido. Ognuno blocca solo qualcosa di nuovo (una nuova richiesta di token, o il prossimo rinnovo) mentre il token di accesso già in mano continua a funzionare finché non scade la propria TTL.

Evento	Effetto
Il client secret dell’applicazione OAuth viene ruotato	Le nuove richieste di token o di rinnovo che usano il vecchio secret vengono rifiutate immediatamente. Un token di accesso già emesso non è interessato e continua a funzionare finché non scade naturalmente.
L’applicazione OAuth o il suo utente di servizio viene rimosso	Blocca l’emissione di nuovi token per quell’applicazione. I token già emessi non vengono revocati in modo proattivo.
Gli scope dell’applicazione OAuth vengono modificati	Un token di accesso già emesso mantiene i propri scope originali per il resto della sua vita. Il token adotta i nuovi scope solo al successivo rinnovo o riemissione.
La grant viene revocata esplicitamente	Blocca immediatamente il prossimo tentativo di rinnovo. Il token di accesso ancora valido non viene fatto scadere forzatamente e continua a funzionare finché non scade naturalmente.

Nota

La finestra di esposizione pratica dopo uno qualsiasi di questi eventi è la TTL propria del token di accesso (circa un’ora), non quella del token di rinnovo, poiché nessuno di essi tocca un token già emesso. Per azzerare subito questa finestra, revoca la grant e ruota il secret insieme, quindi considera l’integrazione non autorizzata finché non è trascorsa una TTL di token di accesso.

Prossimi passi

• Codici di errore per il dettaglio completo delle risposte 401 e 403
• Flusso Client Credentials, Flusso Native Application o Flusso Authorization Code + redirect personalizzato per ottenere il tuo primo token