Valideer Access Token

De API dient de geldigheid van het access token en de toegestane scopes voor dit request te valideren

Voor deze validatie kan de API terecht op het Introspection Endpoint: de concrete URL hiervoor kan teruggevonden worden op de Discovery URL.

oAuth token exchange - valideer access token

Conform de standaard kunnen volgende parameters meegestuurd worden:

Parameter Omschrijving
token VERPLICHT Het Access Token dat gevalideerd moet worden
token_type_hint OPTIONEEL een hint om het type token mee te geven, in dit geval access_token. Indien je weet dat het over een refresh token gaat, kan je refresh_token gebruiken.

Voor de authenticatie zijn er meerdere mogelijkheden:

ClientID en Secret via POST-parameters

Hierbij worden de ClientID en de Secret via POST-parameters doorgestuurd.

Voorbeeld:

POST /op/v1/introspect HTTP/1.1
Host: authenticatie.vlaanderen.be
Accept: application/json
Content-Type: application/x-www-form-urlencoded

  client_id=37f875cb-a7bd-4724-ac39-4729092f8412&
  client_secret=AbcjSBQwSoBeIuebd40U-Dtj8uccpZa-B7eigKOoCpnHoeHjcb0IkseYA8zhMdYKlpzQajefj4OhjvkVEXq6clvKlutFAbc&
  token=Geh30TieWrbRdlsnCLDJDezs63ne2djdh8eSxhznd5b&
  token_type_hint=access_token

ClientID en Secret via Basic Authentication

De ClientID en Secret worden via Basic Authentication “Authorization”-header meegestuurd.

POST /op/v1/introspect HTTP/1.1
Host: authenticatie.vlaanderen.be
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Basic MzdmODc1Y2ItYTdiZC00NzI0LWFjMzktNDcyOTA5MmY4NDEyOkFiY2pTQlF3U29CZUl1ZWJkNDBVLUR0ajh1Y2NwWmEtQjdlaWdLT29DcG5Ib2VIamNiMElrc2VZQTh6aE1kWUtscHpRYWplZmo0T2hqdmtWRVhxNmNsdktsdXRGQWJjCg==

  token=Geh30TieWrbRdlsnCLDJDezs63ne2djdh8eSxhznd5b&
  token_type_hint=access_token

Client authenticatie via een JWT token

In dit geval genereert de Client bij de onboarding een asymmetrisch keypaar en bezorgt de Authorization Server het publieke deel ervan: het private deel wordt enkel lokaal op de Client bewaard.

Bij de authenticatie op het Token Endpoint worden volgende parameters meegestuurd:

  • “client_assertion_type” met als waarde “urn:ietf:params:oauth:client-assertion-type:jwt-bearer”
  • “client_assertion” met daarin één enkele JWT

Voorbeeld:

POST /op/v1/introspect HTTP/1.1
Host: authenticatie.vlaanderen.be
Accept: application/json
Content-Type: application/x-www-form-urlencoded

  token=Geh30TieWrbRdlsnCLDJDezs63ne2djdh8eSxhznd5b&
  token_type_hint=access_token&
  client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&
  client_assertion=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiIyODM1ODgxNC01YzIwLTRjMTMtYmJmZi1kYjVkZDhjNGFlOTMiLCJzdWIiOiIyODM1ODgxNC01YzIwLTRjMTMtYmJmZi1kYjVkZDhjNGFlOTMiLCJhdWQiOiJodHRwczovL2F1dGhlbnRpY2F0aWUudmxhYW5kZXJlbi5iZS9vcCIsImV4cCI6MTU5MjIwODA2MCwianRpIjoiRGt6bmpzdTQzZHprZDN6amQ1IiwiaWF0IjoxNTkyMjA4MDAwfQ.3dPodaVhJ2d3cXWn0v2YGeZqs5XScJF2lm4MaweDnf4

In bovenstaand request bevatte “client_assertion” een JWT met volgende inhoud:

{
  "iss": "37f875cb-a7bd-4724-ac39-4729092f8412",
  "sub": "37f875cb-a7bd-4724-ac39-4729092f8412",
  "aud": "https://authenticatie.vlaanderen.be/op",
  "exp": 1592208060,
  "jti": "74e0d940-f0eb-451c-af4b-46924f5db0fc",
  "iat": 1592208000
}

De JWT in de client_assertion dient uiteraard gesigned te zijn met één van de keys die voor die API geregistreerd staan op de Authorization Server.

Daarnaast moet/kan deze JWT volgende claims bevatten:

Claim Omschrijving
iss (issuer) VERPLICHT Deze dient de ClientID te bevatten
sub (subject) VERPLICHT Deze dient de ClientID te bevatten
aud (audiance) VERPLICHT Deze dient de issuer te bevatten, zijnde https://authenticatie-ti.vlaanderen.be/op voor TEST of https://authenticatie.vlaanderen.be/op voor PROD
exp (expiration time) VERPLICHT Een expiration time moet aanwezig zijn: de huidige tijd mag niet recenter zijn dan de expiration time en deze mag ook niet te ver in de toekomst liggen (maximum 10 minuten)
jti (jwt id) OPTIONEEL AANBEVOLEN Men kan een unieke ID meegeven voor de JWT: de Authorization Server kan dit gebruiken om replay attacks tegen te gaan
iat (issued at) OPTIONEEL Tijdstip waarop de JWT werd gegenereerd: deze mag niet te ver in de toekomst liggen
nbf (not before) OPTIONEEL Indien aanwezig worden tokens niet aanvaard voor de aangegeven timestamp