Aanvraag Access Token

De Client vraagt een Access Token aan en authenticeert zich hiervoor

De Client maakt gebruik van de oAuth Client Credential Grant voor de aanvraag van een Access Token.

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

oAuth server-naar-server

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 audience waar je het access_token wenst te gebruiken
resource OPTIONEEL de resource waar je het access_token wenst te gebruiken

Default scopes

Een client kan bij onboarding 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.

audience/resource

Wanneer geen (geldige) audience of resource parameters worden meegegeven, zal het access token als audience de client_id krijgen van de client die zich authenticeert. In de meest voorkomende usecases zal het bekomen access_token gebruikt worden om de client te authenticeren bij een API (met andere client_id) Om aan te geven voor welke audience(s) het access token geldig moet zijn, kan via de parameter audience de gewenste client_id duidelijk gemaakt worden.

Indien de client_id van de resource server niet gekend is, kan u de URL van de resource die je zal opvragen meegeven in de parameter resource. Op basis van deze resource zal dan de juiste client_id in de audience van het access token gezet worden. Dit zal correct werken wanneer de resource server bij onboarding de doorgegeven URL koppelde aan zijn client_id. Indien dit niet gebeurde, zal de gevraagde resource genegeerd worden.

Zowel de parameters audience als resource kunnen meerdere keren gespecifieerd worden, wat toe laat om access_tokens te bekomen die geldig zijn voor meerdere resource servers.

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.

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=AppRead%20AppWrite

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=AppRead%20AppWrite

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/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=AppRead%20AppWrite&
  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 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