Token
A che cosa servono ID token, access token e refresh token, chi valida quale, quanto durano e come funzionano rotazione e conservazione sicura.
Un singolo accesso può produrre tre token diversi, e la maggior parte dei problemi di integrazione nasce dal confondere lo scopo di ciascuno. Questa pagina è la tabella di consultazione: scopo, audience, durata e regole di gestione per ogni tipo di token.
I tre token
| Token | Destinatario | A che cosa serve | Validato da |
|---|---|---|---|
| ID token | L'applicazione (il suo client ID è l'audience) | Dimostra chi ha effettuato l'accesso e trasporta i claim di profilo (sub, name, email, ...). | L'applicazione, di norma tramite la propria libreria OIDC. |
| Access token | Un'API (il suo identificatore è l'audience) | Autorizza le chiamate a quella API e trasporta gli scope concessi. | L'API, a ogni richiesta; vedere Proteggere un'API. |
| Refresh token | La piattaforma stessa | Consente all'applicazione di rinnovare il proprio access token in un secondo momento, senza rimandare l'utente alla pagina di accesso. | La piattaforma, sul token endpoint. |
L'errore più frequente è inviare l'ID token a un'API. Un ID token autentica l'utente presso l'applicazione e la sua audience è il client ID dell'applicazione, quindi un'API implementata correttamente lo rifiuta. Alle API va inviato l'access token, che all'interno del client va trattato come opaco: il suo contenuto è un accordo tra la piattaforma e l'API, non con l'applicazione.
Formati degli access token
- Per un'API registrata (il client ha passato l'identificatore dell'API come resource indicator): un JWT firmato con l'identificatore dell'API in
aud, gli scope concessi inscopee il chiamante insub. L'API lo valida offline rispetto alle chiavi pubblicate dalla piattaforma. Con l'RBAC abilitato trasporta anche i claimpermissions/roles. - Senza un'API di destinazione: un token opaco, utilizzabile soltanto sull'endpoint UserInfo della piattaforma. I token opachi (e i refresh token) possono essere verificati sull'endpoint standard di token introspection e annullati sull'endpoint di revoca; entrambi sono elencati nel documento di discovery. Un client può eseguire l'introspection dei propri token; i token di altri client solo un'applicazione creata nella Admin Console con un client secret o una chiave (un resource server), non una registrata dinamicamente.
Durate
| Token / artefatto | Durata | Dove si configura |
|---|---|---|
| Authorization code | 1 minuto, monouso | Fisso |
| Access token per un'API | 1 giorno per impostazione predefinita (2 ore con i flussi impliciti) | Per singola API, nella relativa scheda delle impostazioni; vedere API |
| Access token senza un'API di destinazione (UserInfo) | 1 ora | Fisso |
| Token machine-to-machine senza un'API di destinazione | 10 minuti | Fisso |
| ID token | 1 ora per impostazione predefinita | Per singola applicazione; vedere Applicazioni |
| Refresh token | 14 giorni, prolungabili dalla rotazione fino a 1 anno complessivo | Fisso; vedere di seguito |
| Device code | 10 minuti | Fisso |
| Sessione di single sign-on | Timeout di inattività e assoluto | A livello di istanza in Impostazioni → Accesso, sovrascrivibile per singola directory; vedere Impostazioni di accesso |
Refresh token
Quando ne viene emesso uno. L'applicazione deve avere abilitato il grant type refresh token. Le applicazioni first-party (senza schermata di consenso) ne ricevono uno automaticamente; le applicazioni con Richiedi il consenso dell'utente attivo ne ricevono uno solo se l'utente ha concesso lo scope offline_access.
Rotazione. I refresh token ruotano anziché durare per sempre:
- Un client public (applicazione single-page o nativa, senza client secret) riceve un refresh token sostitutivo a ogni utilizzo. Per i client basati su browser il sostitutivo mantiene la durata residua, quindi la rotazione non la prolunga.
- Un client confidential conserva il proprio refresh token finché non è trascorso circa il 70% della sua durata; l'utilizzo successivo emette allora un nuovo token da 14 giorni.
- Comunque avvenga la rotazione, una catena di refresh token termina al più tardi un anno dopo l'accesso originario; da quel momento l'utente deve accedere di nuovo.
Un refresh token sostituito dalla rotazione (già usato) non è più valido; se il client conserva i token, va sempre memorizzato il più recente ricevuto in ciascuna risposta.
Revoca. Un'applicazione può annullare in anticipo un refresh token sull'endpoint di revoca (elencato nel documento di discovery), buona pratica durante la propria procedura di disconnessione. Gli utenti possono terminare le proprie sessioni dal portale del proprio account («disconnessione ovunque»), e i token vincolati alla sessione terminano con essa; vedere la sezione seguente.
Token e disconnessione
La disconnessione termina la sessione SSO della piattaforma, ma i token seguono regole proprie:
- I token emessi senza
offline_accesssono vincolati alla sessione. I token opachi smettono di funzionare nel momento in cui la sessione termina. - Un access token JWT non può essere richiamato: le API lo validano offline, quindi resta tecnicamente utilizzabile fino alla scadenza anche dopo la disconnessione. Se quella finestra è rilevante per un'API, conviene ridurne la durata dell'access token anziché affidarsi al logout.
- I refresh token ottenuti con
offline_accesssopravvivono alla disconnessione per scelta progettuale (è proprio questo il significato dell'accesso offline). Terminano alla scadenza, al raggiungimento del limite di un anno oppure con la revoca. - Le applicazioni possono essere informate della disconnessione tramite il back-channel logout; vedere Durate dei token e logout. Il rapporto tra la sessione della piattaforma, le sessioni delle applicazioni e la sessione di un provider di identità a monte è descritto in Ciclo di vita degli utenti: sessioni.
Conservazione dei token
- Contro gli script in esecuzione nella pagina (cross-site scripting): un token in
localStorageosessionStorageè leggibile da qualsiasi script iniettato. Le applicazioni browser conservano i token solo in memoria e si affidano alla rotazione dei refresh token per coprire la breve durata dell'access token. - Contro altro software presente sul dispositivo: un token in un file semplice o in un archivio di preferenze è a una lettura di distanza. Le applicazioni native utilizzano l'archivio protetto del sistema operativo (Keychain, Keystore, credential locker).
- Contro il browser nel suo complesso: un'applicazione lato server non ha mai bisogno che il browser custodisca un token. Conviene conservare i token sul server, legati al proprio cookie di sessione.
- Contro le fughe in transito e nei log: inviare i token solo su TLS nell'header
Authorization, mai negli URL (finiscono nei log dei proxy e dei server), e non scriverli mai nei log per conto proprio.
Argomenti correlati
- Proteggere un'API: validare gli access token nella propria API.
- API: scope, audience e impostazioni dei token per singola API.
- Applicazioni: impostazioni di token e logout per singola applicazione.
- Impostazioni di accesso: i timeout della sessione SSO.