# 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 [#the-three-tokens]

| 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](https://dts-identity.com/it/docs/quickstarts/protect-an-api.md). |
| **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 [#access-token-formats]

- **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 in `scope` e il chiamante in `sub`. L'API lo valida offline rispetto alle chiavi pubblicate dalla piattaforma. Con l'[RBAC](https://dts-identity.com/it/docs/integrations/apis.md#role-based-access-control) abilitato trasporta anche i claim `permissions` / `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 [#lifetimes]

| 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](https://dts-identity.com/it/docs/integrations/apis.md) |
| 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](https://dts-identity.com/it/docs/integrations/applications.md#token-lifetimes-and-logout) |
| 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](https://dts-identity.com/it/docs/settings/login.md) |

## Refresh token [#refresh-tokens]

**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 [#tokens-and-sign-out]

La disconnessione termina la sessione SSO della piattaforma, ma i token seguono regole proprie:

- I token emessi **senza** `offline_access` sono 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_access` sopravvivono 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](https://dts-identity.com/it/docs/integrations/applications.md#token-lifetimes-and-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](https://dts-identity.com/it/docs/directories/user-lifecycle.md#sessions).

## Conservazione dei token [#storing-tokens]

- **Contro gli script in esecuzione nella pagina** (cross-site scripting): un token in `localStorage` o `sessionStorage` è 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](https://dts-identity.com/it/docs/quickstarts/protect-an-api.md): validare gli access token nella propria API.
- [API](https://dts-identity.com/it/docs/integrations/apis.md): scope, audience e impostazioni dei token per singola API.
- [Applicazioni](https://dts-identity.com/it/docs/integrations/applications.md): impostazioni di token e logout per singola applicazione.
- [Impostazioni di accesso](https://dts-identity.com/it/docs/settings/login.md): i timeout della sessione SSO.
