Bij Koppeltaal worden er ondertekende (HTI) tokens tussen applicaties uitgewisseld dat verifieerbare informatie bevat. De ontvanger van deze (HTI) tokens heeft een manier nodig om deze token te kunnen verifiëren. De kernspecificaties van OAuth 2.0 definieert geen specifieke methode voor het verifiëren van deze tokens, maar vermeldt alleen dat coördinaties tussen de ontvanger van het token en autorisatie server vereist is.
OAuth 2.0 Token Introspection heeft een protocol uitbreiding gedefinieerd dat informatie retourneert over een JSON Web token, bedoeld om te worden gebruikt door ontvangende partijen die zelf niet het token verifiëren.
De specificaties van de token introspectie kan men vinden in RFC7662.
Het token introspection endpoint moet informatie over een token kunnen retourneren, dus dit endpoint zit meestal op dezelfde locatie waar de tokens worden uitgegeven.
Het verzoek om een token te laten valideren gebeurt met een POST-verzoek dat alleen een parameter met de naam "token" bevat.
Het endpoint wordt niet publiekelijk beschikbaar gesteld en wordt met een toegangstoken afgeschermd.
POST /introspect HTTP/1.1 Host: koppeltaal.nl Accept: application/json Content-Type: application/x-www-form-urlencoded Authorization: Bearer 23410913-abewfq.123483 token=2YotnFZFEjr1zCsicMWpAA
Het antwoord op het token introspection verzoek is een JSON object met de volgende elementen. Alleen het element 'active' is vereist, alle andere elementen die in het antwoord teruggeven worden zijn optioneel. Sommige van deze optionele elementen zijn specifiek voor JWT-tokens, anderen zijn toegevoegd als launch parameters.
| element | omschrijving |
|---|---|
| active | Geeft aan of het token niet is ingetrokken door de autorisatie server en niet verlopen is. Dus of het token authentiek is en de integriteit van het token gewaarborgd is |
| scope | Een JSON string gescheiden door spaties die een lijst van scopes (domeinen) gekoppeld heeft aan dit token, zoals vastgelegd in JWT (RFC6749) |
| client_id | De client_id voor de OAuth 2.0 client waaraan het token is uitgegeven. |
| username | Een leesbare id voor de gebruiker die dit token heeft geautoriseerd |
| exp | (UNIX) tijdstempel dat aangeeft wanneer dit token verloopt, zoals vastgelegd in JWT (RFC7519) |
| sub | Het onderwerp van het token, zoals vastgelegd in JWT (RFC7519) |
| aud | Doelgroep voor wie het token bedoeld is, zoals vastgelegd in JWT (RFC7519) |
| iss | De uitgever van het token, zoals vastgelegd in JWT (RFC7519) |
| user | Gebruiker die lanceert; Patient, Practitioner, RelatedPerson |
| patient | Patiënt context van de launch (behandeling) |
| fhirContext | Referentie naar fhir resources, zoals Task |
| intent | Intentie van de launch (view) |
HTTP/1.1 200 OK
Content-Type: application/json
{
"active": true,
"client_id": "l238j323ds-23ij4",
"sub": "Z5O3upPC88QrAjx00dis",
"aud": "https://Koppeltaal.nl/eHealthModule/123",
"iss": "https://Koppeltaal.Authorization.nl/",
"exp": 1419356238,
"iat": 1419350238,
"user": "Practitioner/123",
"patient": "123",
"fhirContext": ["https://Koppeltaal.nl/Task/123"],
"intent": "samenstellen-behandeling"
}
Als het introspectie endpoint openbaar toegankelijk is, moet het endpoint eerst de (applicatie) authenticatie verificatie valideren.
Als de verificatie ongeldig is, moet het endpoint een HTTP 401-statuscode en een 'invalid_client' antwoord retourneren.
HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
{
"error": "invalid_client",
"error_description": "The client authentication was invalid"
}
Elke andere fout wordt beschouwd als een "inactive" token. Zie volgende mogelijkheden:
- Het aangevraagde token bestaat niet of is ongeldig
- Het token is verlopen
- Het token is uitgegeven aan een andere klant dan dit verzoek doet
In al deze gevallen wordt het niet als een foutmelding beschouwd en retourneert het endpoint "active": false.