Aanvraag API Access Token

De (frontend) toepassing vraagt wisselt de verkregen Authorization Code in voor een API Access Token

Om een API Access Token te verkrijgen kan de (frontend) toepassing terecht op het Token Endpoint: de URL hiervoor kan teruggevonden worden op het Discovery Endpoint.

oAuth server-naar-server

De frontend (Toepassing) zal nu de Authorization Code bij het Token Endpoint inwisselen voor een API Access Token (en optioneel een Refresh Token): dit dient binnen de 30 seconden te gebeuren.

Volgende parameters zijn hierbij vereist:

Parameter		Omschrijving
grant_type	VERPLICHT	Waarde die verplicht “authorization_code” is
code	VERPLICHT	de Authorization Code die van de Authorization Server werd bekomen
client_id	VERPLICHT	Client ID van de (frontend) toepassing: ofwel direct vermeldt in de request bij gebruik van client secret ofwel vermeldt in de client assertion bij gebruik van JWT
redirect_uri	VERPLICHT	redirect URI die verbonden zijn aan de client ID van de (frontend) toepassing

Voor de authenticatie zijn er meerdere 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 (frontend) toepassing bezorgd. Deze ClientID en Secret kunnen door de (frontend) toepassing op 2 verschillende manieren aangeboden worden aan het Token Endpoint.

Tip

De secret die aan de (frontend) toepassing wordt, 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 van de frontend (toepassing) 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&
  code=OV9FU_1lxJoAbc&
  grant_type=authorization_code&
  redirect_uri=https%3A%2F%2Fmijntoepassing%2Fcallback

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

  code=OV9FU_1lxJoAbc&
  grant_type=authorization_code&
  redirect_uri=https%3A%2F%2Fmijntoepassing%2Fcallback

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/token HTTP/1.1
Host: authenticatie.vlaanderen.be
Content-Type: application/x-www-form-urlencoded

  code=OV9FU_1lxJoAbc&
  grant_type=authorization_code&
  redirect_uri=https%3A%2F%2Fmijntoepassing%2Fcallback&
  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 private keys waarvan de publieke keys geregistreerd staat op de Authorization Server.

Daarnaast moet/kan deze JWT volgende claims bevatten:

Claim		Omschrijving
iss (issuer)	VERPLICHT	Deze dient de ClientID van de (frontend) toepassing bevatten te bevatten
sub (subject)	VERPLICHT	Deze dient de ClientID van de (frontend) toepassing bevatten 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

Aangezien de (frontend) toepassing 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 (frontend) toepassingen. Selecteer hier enkel JWT token als u enkel dit mechanisme wil toelaten.

De implementatie details zoals beschreven bij de interactieve oAuth authenticatie zijn verder ook van toepassing.