# Tokens

Waarvoor ID-, access- en refresh tokens dienen, wie welk token valideert, hoe lang ze leven en hoe rotatie en veilige opslag werken.

Eén aanmelding kan drie verschillende tokens opleveren, en de meeste integratieproblemen ontstaan doordat verward raakt waarvoor elk ervan dient. Deze pagina is de opzoektabel: doel, audience, levensduur en omgangsregels per tokentype.

## De drie tokens [#the-three-tokens]

| Token | Gericht aan | Waarvoor het dient | Gevalideerd door |
|---|---|---|---|
| **ID token** | De applicatie (haar client ID is de audience) | Toont aan *wie zich heeft aangemeld* en draagt profielclaims (`sub`, `name`, `email`, ...). | De applicatie, doorgaans via haar OIDC-bibliotheek. |
| **Access token** | Een API (haar identifier is de audience) | Autoriseert *aanroepen van die API* en draagt de verleende scopes. | De API, bij elke aanvraag; zie [Een API beschermen](https://dts-identity.com/nl/docs/quickstarts/protect-an-api.md). |
| **Refresh token** | Het platform zelf | Laat de applicatie haar access token later vernieuwen zonder de gebruiker terug naar de aanmeldpagina te sturen. | Het platform, bij het token-eindpunt. |

De meest gemaakte fout is het **ID token naar een API sturen**. Een ID token authenticeert de gebruiker *tegenover de applicatie* en zijn audience is de client ID van de applicatie, dus een correct geïmplementeerde API wijst hem af. Stuur het **access token** naar API's en behandel het binnen de client als ondoorzichtig: de inhoud ervan is een contract tussen het platform en de API, niet met de applicatie.

## Formaten van access tokens [#access-token-formats]

- **Voor een geregistreerde API** (de client heeft de identifier van de API als resource indicator meegegeven): een **ondertekend JWT** met de identifier van de API als `aud`, de verleende scopes in `scope` en de aanroeper in `sub`. De API valideert het offline tegen de gepubliceerde sleutels van het platform. Met [RBAC](https://dts-identity.com/nl/docs/integrations/apis.md#role-based-access-control) ingeschakeld draagt het bovendien de claims `permissions` en `roles`.
- **Zonder doel-API**: een **opaak** token, dat alleen bij het UserInfo-eindpunt van het platform bruikbaar is. Opake tokens (en refresh tokens) kunnen bij het standaard token-introspection-eindpunt worden gecontroleerd en bij het revocation-eindpunt worden ingetrokken; beide staan in het discovery-document. Een client mag zijn eigen tokens introspecteren; tokens van andere clients alleen een applicatie die in de Admin Console is aangemaakt met een client secret of sleutel (een resource server), niet een dynamisch geregistreerde.

## Levensduren [#lifetimes]

| Token / artefact | Levensduur | Waar geconfigureerd |
|---|---|---|
| Authorization code | 1 minuut, eenmalig te gebruiken | Vast |
| Access token voor een API | Standaard 1 dag (2 uur via implicit-flows) | Per API, op haar tabblad Instellingen; zie [API's](https://dts-identity.com/nl/docs/integrations/apis.md) |
| Access token zonder doel-API (UserInfo) | 1 uur | Vast |
| Machine-to-machine-token zonder doel-API | 10 minuten | Vast |
| ID token | Standaard 1 uur | Per applicatie; zie [Applicaties](https://dts-identity.com/nl/docs/integrations/applications.md#token-lifetimes-and-logout) |
| Refresh token | 14 dagen, door rotatie te verlengen tot in totaal maximaal 1 jaar | Vast; zie hieronder |
| Device code | 10 minuten | Vast |
| Sessie voor eenmalige aanmelding | Inactiviteits- en absolute time-outs | Instantiebreed onder **Instellingen → Aanmelding**, per directory te overschrijven; zie [Aanmeldingsinstellingen](https://dts-identity.com/nl/docs/settings/login.md) |

## Refresh tokens [#refresh-tokens]

**Wanneer er een wordt uitgegeven.** De applicatie moet het grant type **refresh token** hebben ingeschakeld. First-party-applicaties (zonder toestemmingsscherm) krijgen er dan automatisch een; applicaties met **Toestemming van gebruiker vereisen** ingeschakeld krijgen er alleen een wanneer de gebruiker de scope `offline_access` heeft verleend.

**Rotatie.** Refresh tokens roteren in plaats van eeuwig te leven:

- Een **public** client (single-page- of native app, zonder client secret) krijgt bij **elk gebruik** een vervangend refresh token. Bij browsergebaseerde clients behoudt de vervanger de resterende levensduur, dus rotatie verlengt die niet.
- Een **confidential** client houdt zijn refresh token tot ongeveer 70% van de levensduur is verstreken; het volgende gebruik geeft dan een nieuw token van 14 dagen uit.
- Hoe er ook wordt geroteerd, een keten van refresh tokens eindigt uiterlijk **één jaar** na de oorspronkelijke aanmelding; daarna moet de gebruiker zich opnieuw aanmelden.

Een weggeroteerd (gebruikt) refresh token is ongeldig; bewaart uw client tokens, sla dan altijd het nieuwste uit elk antwoord op.

**Intrekken.** Een applicatie kan een refresh token proactief intrekken bij het revocation-eindpunt (vermeld in het discovery-document), wat bij uw eigen afmelding goede hygiëne is. Gebruikers kunnen hun sessies vanuit hun accountportaal beëindigen ("overal afmelden"), en sessiegebonden tokens eindigen daarmee; zie de volgende sectie.

## Tokens en afmelden [#tokens-and-sign-out]

Afmelden beëindigt de SSO-sessie van het platform, maar tokens volgen hun eigen regels:

- Tokens die **zonder** `offline_access` zijn uitgegeven, zijn aan de sessie gebonden. Opake tokens werken niet meer vanaf het moment dat de sessie eindigt.
- Een **JWT access token kan niet worden teruggeroepen**: API's valideren het offline, dus het blijft ook na de afmelding tot zijn verloop technisch bruikbaar. Is dat tijdvenster voor een API van belang, verkort dan haar levensduur van access tokens in plaats van op het uitloggen te vertrouwen.
- **Met `offline_access` verkregen refresh tokens overleven de afmelding** met opzet (precies dat betekent offline access). Ze eindigen wanneer ze verlopen, de grens van één jaar bereiken of worden ingetrokken.
- Applicaties kunnen via **back-channel logout** over de afmelding worden *geïnformeerd*; zie [Token-levensduren en logout](https://dts-identity.com/nl/docs/integrations/applications.md#token-lifetimes-and-logout). Hoe de platformsessie, de applicatiesessies en de sessie van een bovenliggende identityprovider samenhangen, beschrijft [Gebruikerslevenscyclus: Sessies](https://dts-identity.com/nl/docs/directories/user-lifecycle.md#sessions).

## Tokens opslaan [#storing-tokens]

- **Tegen scripts in de pagina** (cross-site scripting): een token in `localStorage` of `sessionStorage` is leesbaar voor elk geïnjecteerd script. Browserapplicaties houden tokens alleen in het geheugen en overbruggen de korte levensduur van het access token met rotatie van refresh tokens.
- **Tegen andere software op het apparaat**: een token in een gewoon bestand of een voorkeurenopslag is één bestandslezing verwijderd. Native apps gebruiken de beschermde opslag van het besturingssysteem (Keychain, Keystore, credential locker).
- **Tegen de browser als geheel**: een serverzijdige applicatie heeft de browser nooit nodig om een token te bewaren. Houd tokens op de server, gekoppeld aan uw eigen sessiecookie.
- **Tegen lekken tijdens het transport en in logboeken**: stuur tokens alleen over TLS in de header `Authorization`, nooit in URL's (daar belanden ze in proxy- en serverlogboeken), en schrijf ze nooit zelf naar logboeken.

## Verwant

- [Een API beschermen](https://dts-identity.com/nl/docs/quickstarts/protect-an-api.md): access tokens in uw eigen API valideren.
- [API's](https://dts-identity.com/nl/docs/integrations/apis.md): scopes, audiences en tokeninstellingen per API.
- [Applicaties](https://dts-identity.com/nl/docs/integrations/applications.md): token- en logout-instellingen per applicatie.
- [Aanmeldingsinstellingen](https://dts-identity.com/nl/docs/settings/login.md): de time-outs van de SSO-sessie.
