Valideer API Access Token

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

Voor deze validatie kan de API Resource 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 API 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.
token_endpoint_auth OPTIONEEL laat toe om info op te vragen met betrekking tot de authenticatie op het token endpoint wanneer dit token werd verkregen.

token_endpoint_auth

Door de optionele parameter token_endpoint_auth te specifieren, kan je extra info bekomen over de authenticatie van de (frontend) toepassing op het token endpoint wanneer het API access token werd uitgegeven. Met de waarde credential_manager (de enige ondersteunde waarde) kan het response informatie terug geven over de organisatie die de gebruikte credential configureerde. Deze info zal aan het antwoord worden toegevoegd indien ze gekend is. Indien dit niet gekend is, zal de parameter genegeerd worden.

Voorbeeld response:

{'active': True,
 'client_id': 'da15d69a-f33e-4a44-83de-ee7dbed9f983',
 'credential_manager': {'code': '0316380841', 'name': 'Ministeries van de Vlaamse Gemeenschap'},
 'exp': 1663017425,
 'iat': 1662988625,
 'iss': 'https://authenticatie.vlaanderen.be/op',
 'scope': 'vo',
 'sub': 'Z5O3upPC88QrAjx00dis',
 'token_type': 'bearer'}

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 (frontend) toepassing bij de onboarding een asymmetrisch keypaar en bezorgt de Authorization Server het publieke deel ervan: het private deel wordt enkel lokaal op de (frontend) toepassing 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 van de API Resource te bevatten
sub (subject) VERPLICHT Deze dient de ClientID van de API Resource 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