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
| 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. |
| 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
- 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 inscopeen de aanroeper insub. De API valideert het offline tegen de gepubliceerde sleutels van het platform. Met RBAC ingeschakeld draagt het bovendien de claimspermissionsenroles. - 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
| 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 |
| 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 |
| 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 |
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
Afmelden beëindigt de SSO-sessie van het platform, maar tokens volgen hun eigen regels:
- Tokens die zonder
offline_accesszijn 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_accessverkregen 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. Hoe de platformsessie, de applicatiesessies en de sessie van een bovenliggende identityprovider samenhangen, beschrijft Gebruikerslevenscyclus: Sessies.
Tokens opslaan
- Tegen scripts in de pagina (cross-site scripting): een token in
localStorageofsessionStorageis 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: access tokens in uw eigen API valideren.
- API's: scopes, audiences en tokeninstellingen per API.
- Applicaties: token- en logout-instellingen per applicatie.
- Aanmeldingsinstellingen: de time-outs van de SSO-sessie.