OAuth 2.0-token introspectie

OAuth 2.0-token introspectie definieert een methode waarmee een geautoriseerde beschermde bron de autorisatieserver kan bevragen om de metadata te bepalen die aan een bepaald token zijn gekoppeld (ofwel een toegangstoken of een ververstoken), verstrekt door een OAuth-client. Op basis van de metadata van het specifieke token kan de bronseigenaar toegang krijgen tot de beschermde bron.

Deze metadata omvatten:

• Of het token momenteel actief is (of het is verlopen of ingetrokken)
• De permissies die het toegangstoken verleent (meestal weergegeven via OAuth 2.0 scopes)
• De autorisatiecontext waarin het token is verleend (inclusief wie het token heeft geautoriseerd en aan welke client het is uitgegeven)

Token introspectie stelt de beschermde bron in staat om deze informatie op te vragen, ongeacht of deze in het token zelf is opgenomen.

Er zijn twee soorten toegangstokens, afhankelijk van hoe ze zijn gecodeerd:

• Identifier-gebaseerd: Het token vertegenwoordigt een willekeurige, moeilijk te raden identifier die is gekoppeld aan de autorisatie in de database van de autorisatieserver.
• Zelfbevatten: De autorisatie is gecodeerd binnen het token zelf en wordt beschermd door cryptografie om manipulatie te voorkomen. JSON Web Token (JWT) is de gangbare standaard voor deze methode.

Voor zelfbevatten tokens kan de autorisatie-gerelateerde metadata direct uit het toegangstoken worden geparseerd. Voor identifier-gebaseerde tokens moet echter de token introspectiefunctie van de autorisatieserver worden gebruikt om de metadata te valideren/op te halen.

Token introspectieverzoek#

Het gebruik van identifier-gebaseerde toegangstokens vereist verificatie met de autorisatieserver via een netwerkverzoek. Er is een standaardprotocol hiervoor genaamd OAuth 2.0 Token Introspection (RFC 7662).

De beschermde bron zal het token naar het introspectie-eindpunt van de autorisatieserver POSTen, en in ruil daarvoor ontvangt het een JSON-object dat de tokenparameters bevat.

Let op dat introspectieverzoeken niet willekeurig kunnen worden geïnitieerd; ze moeten aan een van de volgende voorwaarden voldoen:

• Authenticatie met behulp van referenties (die vooraf moeten worden geregistreerd bij de autorisatieserver), of
• Autorisatie met behulp van een toegangstoken.

Als gevolg hiervan wordt in deze specifieke interactie de beschermde bron de OAuth-client en de autorisatieserver de beschermde bron.

Hieronder staat een voorbeeld van een introspectieverzoek, waarbij de beschermde bron zich authenticeert met behulp van een client-ID en clientgeheim, die zijn verkregen na registratie als OAuth-client bij de autorisatieserver.

Hieronder staat een voorbeeld van een introspectieverzoek dat rechtstreeks gebruikmaakt van een toegangstoken. Het toegangstoken kan rechtstreeks van het /token eindpunt worden verkregen door gebruik te maken van de referenties van een geregistreerde machine-to-machine app en het client_credentials grant type.

Token introspectierespons#

De belangrijkste parameter is active, een booleaanse waarde. Als true, geeft dit aan dat het token geldig is, en het JSON-object zal andere token details omvatten, zoals de scope waarden. Als false, is het token ongeldig of verlopen, en moet de beschermde bron een 401 Unauthorized-respons retourneren met de invalid_token foutcode.

Hier is een voorbeeldrespons voor een geldig token:

Afgezien van active, dat vereist is, zijn alle andere parameters optioneel.

De beschermde bron kan deze aanvullende velden gebruiken om de toegangsrechten te bepalen, vergelijkbaar met hoe het een JWT-toegangstoken zou parseren en valideren.