Aanvraag API Access Token
De Client maakt gebruik van de oAuth Client Credential Grant voor de aanvraag van een API Access Token om vervolgens een API Resource te raadplegen.
Voor deze validatie kan de Client terecht op het Token Endpoint: de concrete URL hiervoor kan teruggevonden worden op de Discovery URL.
Bij dit verzoek zijn (naast de parameters bedoeld voor de authenticatie) volgende parameters vereist/mogelijk:
Parameter | Omschrijving | |
---|---|---|
grant_type | VERPLICHT | Waarde die verplicht “client_credentials” is |
scope | OPTIONEEL (Indien default scopes gedefinieerd werden) |
de scopes die de Client wenst aan te vragen bij dit toegangsverzoek |
audience | OPTIONEEL | de client_id van de API Resource waarvoor je een accesstoken wenst te bekomen |
resource | OPTIONEEL | de resource (URL) van de API Resource waar je het access_token wenst te gebruiken |
Default scopes
De API Resource kan bij het onboarden van een client specifieke scopes als default scopes laten configureren. Deze scopes zullen dan altijd uitgeleverd worden (indien de autorisatie dit toestaat) voor deze client. Dus ook wanneer deze scopes niet werden aangevraagd in het request, zullen de default scopes worden uitgeleverd.
claims_setbyclient
Specifiek in oAuth Client Credential Grant flows, is het mogelijk om voor een client attributen te definiëren in het beheerportaal. Deze attributen zullen steeds beginnen met setbyclient_, gevolgd door een benaming naar keuze.
Wanneer de speciale scope claims_setbyclient
wordt gevraagd, zullen alle attributen, gelinkt aan de client en die beginnen met setbyclient_ uitgeleverd worden in claims.
audience/resource
Wanneer geen (geldige) audience of resource parameters worden meegegeven, zal het API access token in de parameter audience de client_id krijgen van de client die zich authenticeert bevatten. In de meest voorkomende usecases zal het bekomen access_token gebruikt worden om de client te authenticeren bij een API Resource (met andere client_id) Om aan te geven voor welke API Resources het access token geldig moet zijn, kan via de parameter audience de gewenste client_id van deze API Resources duidelijk gemaakt worden.
Indien de client_id van de API resource niet gekend is, kan u de URL van de API Resource die je zal opvragen meegeven in de parameter resource. Op basis van deze parameter resource zal dan de juiste client_id (die van API Resource) in de audience van het access token gezet worden. Dit zal correct werken wanneer de API resource server bij onboarding de doorgegeven URL koppelde aan zijn client_id. Indien dit niet gebeurde, zal de gevraagde parameter resource genegeerd worden.
Zowel de parameters audience als resource kunnen meerdere keren gespecifieerd worden, wat toe laat om API access tokens te bekomen die geldig zijn voor meerdere API Resources.
Authenticatie mogelijkheden
Client authenticatie op basis van ClientID en Secret
Hierbij wordt er bij de onboarding een ClientID en een Secret gegenereerd langs de Authorization Server zijde en aan de Client bezorgd. Deze ClientID en Secret kunnen door de Client op 2 verschillende manieren aangeboden worden aan het Token Endpoint.
Tip
De secret dat bij de client hoort, dient uiterst confidentieel gehouden te worden. Wanneer je secret (mogelijks) gelekt werd, kan je best contact opnemen om een nieuw secret te laten genereren.ClientID en Secret via POST-parameters
Hierbij worden de ClientID en de Secret via POST-parameters doorgestuurd.
Voorbeeld:
POST /op/v1/token HTTP/1.1
Host: authenticatie.vlaanderen.be
Content-Type: application/x-www-form-urlencoded
client_id=28358814-5c20-4c13-bbff-db5dd8c4ae93&
client_secret=CgNjSBQwSolxUcFe7A0U-16j7uccp34-Z5eigKOoCpn5WMHjcb0IkseYA8zhMdYKlpzNJh4Qj4OhjvkVEXq6clvKlutFv5H&
grant_type=client_credentials&
resource=https://myapi.vlaanderen.be/protected/resource/path&
scope=org_api_appread%20org_api_appwrite
Tip
Het doorsturen van de ClientID en Secret via Querystring parameters (dus in de Request URI) is onveilig en wordt bijgevolg niet ondersteund. Wanneer dit toch is gebeurd, kan u best contact opnemen om een nieuw secret te laten genereren.ClientID en Secret via Basic Authentication
De ClientID en Secret worden via Basic Authentication “Authorization”-header meegestuurd.
POST /op/v1/token HTTP/1.1
Host: authenticatie.vlaanderen.be
Authorization: Basic MjgzNTg4MTQtNWMyMC00YzEzLWJiZmYtZGI1ZGQ4YzRhZTkzOkNnTmpTQlF3U29seFVjRmU3QTBVLTE2ajd1Y2NwMzQtWjVlaWdLT29DcG41V01IamNiMElrc2VZQTh6aE1kWUtscHpOSmg0UWo0T2hqdmtWRVhxNmNsdktsdXRGdjVI
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&
scope=org_api_appread%20org_api_appwrite
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 met meerdere audiences:
POST /op/v1/token HTTP/1.1
Host: authenticatie.vlaanderen.be
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&
audience=8ed36a78-8443-11ec-b334-83e86b606670&
audience=9e6a512c-8443-11ec-ae2c-8700eb2a0cde&
scope=org_api_appread%20org_api_appwrite&
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": "28358814-5c20-4c13-bbff-db5dd8c4ae93",
"sub": "28358814-5c20-4c13-bbff-db5dd8c4ae93",
"aud": "https://authenticatie.vlaanderen.be/op",
"exp": 1592208060,
"jti": "Dkznjsu43dzkd3zjd5",
"iat": 1592208000
}
De JWT in de client_assertion dient uiteraard gesigned te zijn met één van de keys die voor die Client 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 client te bevatten |
sub (subject) | VERPLICHT | Deze dient de ClientID van de client 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 maximaal 10 min in de toekomst liggen |
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 API Access tokens niet aanvaard voor de aangegeven timestamp |
Tip
Aangezien de Client in dit scenario de enige is die het private deel van de Secret kent, is de Client authenticatie via een JWT token de veiligste optie en geniet deze de voorkeur.
Bij de definitie van de API Resource kan aangegeven worden of Client/Secret en/of JWT-token toegestaan is voor de Clients. Selecteer hier enkel JWT token als u enkel dit mechanisme wil toelaten.