Het token introspection endpoint

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 token introspection URL endpoint kan via de FHIR Resource Provider /metadata URL opgevraagd worden.

Het verzoek om een token te laten valideren gebeurt met een POST-verzoek dat alleen een parameter met de naam "token" bevat.

Het token introspection endpoint wordt niet publiekelijk beschikbaar gesteld en wordt met een toegangstoken afgeschermd.

Token Introspection verzoek

POST authentication-service.koppeltaal.headease.nl/oauth2/introspect HTTP/1.1
Host: authentication-service.koppeltaal.headease.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)

Zie ook: http://hl7.org/fhir/smart-app-launch/scopes-and-launch-context.html#launch-context-arrives-with-your-access_token

Antwoord op token introspection verzoek

 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 'Unauthorized' antwoord retourneren.

Niet geautoriseerd voor introspectie

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8

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.