Valideer Access Token
Voor deze validatie kan de API terecht op het Introspection Endpoint: de concrete URL hiervoor kan teruggevonden worden op de Discovery URL.
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. |
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 client op het token endpoint wanneer het 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 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 |
Tip
De Client authenticatie via een JWT token is de veiligste optie en geniet de voorkeur.
In het integratiedossier kan aangegeven worden of Client/Secret en/of JWT-token toegestaan is voor de specifieke API. Selecteer hier enkel JWT token als u van plan bent dit mechanisme te gebruiken.