Levenscyclus van tokens in de praktijk

Elke OAuth-flowgids noemt refresh_token, maar een langlopende integratie (een die over veel aanvragen, workers of dagen blijft draaien) vraagt om meer dan “vervang het token bij verlopen”. Deze pagina behandelt echte tokenlevensduren, het cachen van een token tussen workers, wanneer u moet vernieuwen, en wat een token ongeldig kan maken voordat het anders zou verlopen.

---

Tokenlevensduur per flow

De levensduur van het access token is één vaste duur, gelijk voor elke flow. Die van het refresh token is dat niet: die hangt af van welke OAuth-flow het heeft uitgegeven.

Flow	TTL van access token	TTL van refresh token
Client Credentials-flow	Ongeveer 1 uur	Ongeveer 30 dagen
Native Application-flow (PKCE, loopback-omleiding)	Ongeveer 1 uur	Geen vaste vervaldatum: blijft geldig totdat het door rotatie wordt vervangen of ingetrokken
Authorization Code + aangepaste-omleiding-flow	Ongeveer 1 uur	Geen vaste vervaldatum: blijft geldig totdat het door rotatie wordt vervangen of ingetrokken

Opmerking

Beide Authorization Code-flows geven een refresh token uit zonder enige sessieklok. Het ligt daardoor niet eindeloos ongebruikt: het is een eenmalig token dat bij elke vernieuwing wordt vervangen (zie Race conditions bij gelijktijdig vernieuwen hieronder), en het werkt onmiddellijk niet meer als de grant wordt ingetrokken.

Cache het token, genereer er niet één per aanvraag

Bij elke API-aanroep, of onafhankelijk in elk workerproces, een nieuw access token aanvragen werkt, maar verspilt bij elke afzonderlijke aanvraag een round trip voor een token dat al ongeveer een uur geldig is. Vraag één token aan, cache het (in het geheugen voor één proces, of in een gedeelde store zoals Redis voor een vloot workers) onder de sleutel van de credential die het heeft uitgegeven, en geef het gecachte token door aan elke aanvraag totdat het bijna verloopt.

Dit telt ook voor het refresh token: hoe minder processen het onafhankelijk van elkaar inwisselen, hoe kleiner de kans dat u de hieronder beschreven race condition tegenkomt.

Vernieuw bij verlopen, niet alleen bij een 401

Omdat de TTL van het access token vast en vooraf bekend is, vernieuwt u proactief: houd bij wanneer u het token hebt verkregen (of decodeer de exp-claim ervan) en vraag kort voor dat moment een nieuw token aan, in plaats van te wachten tot een aanvraag eerst mislukt.

Behandel een mislukte aanvraag toch als terugvaloptie, maar maak onderscheid op basis van de ontvangen fout:

• 401 met not_authenticated: de aanvraag bevatte helemaal geen bruikbaar bearer-token. Dit is een bug aan clientzijde (ontbrekende of onjuist gevormde Authorization-header), geen signaal om te vernieuwen.
• 401 met invalid_token: de handtekening- of verlooptijdcontrole van het token is mislukt. Vernieuw en probeer één keer opnieuw.
• 403: nooit een tokenprobleem. Het token is geldig; de aanroeper heeft niet de scope, contenttoegang of rol die de bewerking vereist. Vernieuwen helpt hier niet. Zie Foutcodes: Rate limiting, authenticatie en toegangscontrole voor de volledige uitsplitsing per code.

Race conditions bij gelijktijdig vernieuwen

Een refresh token is eenmalig bruikbaar: het inwisselen ervan met grant_type=refresh_token maakt dat refresh token ongeldig en geeft samen een nieuw access token en een nieuw refresh token uit. Als meerdere workers hetzelfde gecachte refresh token delen en twee daarvan bijna tegelijk proberen te vernieuwen, slaagt slechts één uitwisseling; de andere krijgt een generieke 401, geen te onderscheiden “al gebruikt”-fout.

Opgepast

Laat niet elke worker onafhankelijk vernieuwen tegen een gedeeld refresh token. Wijs één eigenaar aan voor de vernieuwingsaanroep (een lock rond het vernieuwingspad, of een aparte vernieuwingsroutine) en laat de overige workers het resulterende access token uit de gedeelde cache lezen in plaats van zelf te vernieuwen.

Wat een token voortijdig ongeldig maakt

Geen van de onderstaande gebeurtenissen trekt een nog geldig access token direct in. Elk blokkeert alleen iets nieuws (een nieuwe tokenaanvraag, of de volgende vernieuwing) terwijl het access token dat u al hebt, blijft werken totdat de eigen TTL verstrijkt.

Trigger	Effect
Het clientgeheim van de OAuth-applicatie wordt geroteerd	Nieuwe token- of vernieuwingsaanvragen met het oude geheim worden onmiddellijk geweigerd. Een al uitgegeven access token wordt hier niet door beïnvloed en blijft werken tot het van nature verloopt.
De OAuth-applicatie of de bijbehorende servicegebruiker wordt verwijderd	Blokkeert het uitgeven van nieuwe tokens voor die applicatie. Al uitgegeven tokens worden niet proactief ingetrokken.
De scopes van de OAuth-applicatie worden gewijzigd	Een al uitgegeven access token behoudt zijn oorspronkelijke scopes voor de rest van zijn levensduur. Het token neemt de nieuwe scopes pas over bij de volgende vernieuwing of heruitgifte.
De grant wordt expliciet ingetrokken	Blokkeert onmiddellijk de volgende vernieuwingspoging. Het nog geldige access token wordt niet gedwongen te verlopen en blijft werken tot het van nature verloopt.

Opmerking

Het praktische blootstellingsvenster na elk van deze gebeurtenissen is de eigen TTL van het access token (ongeveer een uur), niet die van het refresh token, aangezien geen ervan een al uitgegeven token raakt. Om dat venster meteen naar nul te brengen, trekt u de grant in en roteert u het geheim tegelijk, en behandelt u de integratie daarna als niet geautoriseerd totdat er één TTL van een access token is verstreken.

Wat is de volgende stap?

• Foutcodes voor de volledige uitsplitsing van 401- en 403-reacties
• Client Credentials-flow, Native Application-flow of Authorization Code + aangepaste-omleiding-flow om uw eerste token te verkrijgen