Aanvraag en ontvangen Authorization Code

De (frontend) toepassing wisselt het eerder verkregen OIDC Access Token in voor een Authorization Code door het OIDC Access Token mee te sturen als Bearer Token

De (frontend) toepassing doet een oAuth Authorization Code Grant verzoek richting het Authorization Endpoint: de URL hiervoor kan teruggevonden worden op het Discovery Endpoint.

oAuth server-naar-server

Volgende parameters worden als query parameters meegestuurd:

Parameter		Omschrijving
client_id	VERPLICHT	ClientID van de frontend toepassing (zoals gekend op de ACM IDP)
redirect_uri	VERPLICHT	redirect/callback URI (van de frontend toepassing) waarnaar de Authorization Code gestuurd zal worden (dit meestal dezelfde die gebruikt wordt in de OIDC): deze moet op voorhand gedefinieerd worden op de OpenID Connect Provider: deze wordt URL-encoded
response_type	VERPLICHT	geeft aan welke flow er gevolgd wordt en het gedrag voor het terugsturen van tokens: in ons geval MOET dit steeds “code” zijn
scope	VERPLICHT	De client_id van de API Resource als audience is een verplichte scope (vb: audience:server:client_id:37f875cb-a7bd-4724-ac39-4729092f8412): hierbij is 37f875cb-a7bd-4724-ac39-4729092f8412 de ClientID van de API Resource. Deze kan worden aangevuld met mogelijke scopes, vermeld in het integratiedossier. Meerdere scopes worden door een spatie gescheiden en nadien URL-encoded. Scopes die in het integratiedossier als “verplicht” aangeduid staan, worden per definitie meegestuurd, ook al worden deze niet expliciet aangevraagd.
state	OPTIONEEL	AANBEVOLEN een waarde die de status bewaart tussen het request en de callback: dit kan enerzijds gebruikt worden als bescherming tegen Cross-Site Request Forgery (CSRF, XSRF): dit kan door de waarde van deze parameter cryptografisch te koppelen aan een browser cookie. Anderzijds kan dit gebruikt worden als een sessie-status: in dat geval zou dit dan een waarde moeten zijn waar niets uit op te maken is waarvan de integriteit door de toepassing gevalideerd kan worden. (bvb geen links of parameters gebruiken)
nonce	OPTIONEEL	AANBEVOLEN een waarde om een Client Sessie te koppelen aan het ID-token om “replay attacks” te mitigeren. De waarde die meegestuurd wordt in het Authenticatie Request wordt ongewijzigd terug gestuurd in het ID-token. Voorzie voldoende entropie voor deze waarde om te vermijden dat aanvallers de waarde kunnen raden

Tip

Er dient exact één client ID of Resource van een API Resource gedefinieerd te worden dat vertrouwd moet zijn door de (frontend) toepassing

De (frontend) toepassing wenst de call te doen namens de aangemelde gebruiker. Dit gebeurt door het OIDC Access Token (uitgegeven voor de frontend toepassing) uit de OpenID Connect authenticatie als Bearer token mee te sturen in een “Authorization” Request header veld om deze te wisselen naar een API Token.

Een voorbeeld van een request waar de (frontend) toepassing het OIDC Access Token meestuurt als Bearer token om deze te wisselen naar een API token:

GET /op/v1/auth?
  client_id=28358814-5c20-4c13-bbff-db5dd8c4ae93&
  redirect_uri=https%3A%2F%2Fmijntoepassing.vlaanderen.be%2Fcallback&
  response_type=code&
  scope=vo%20openid%20%20profile%20audience%3Aserver%3Aclient_id%3A37f875cb-a7bd-4724-ac39-4729092f8412&
  state=Fheue34eg2hjsdehfk839ed83azz&
  nonce=FJEkzudnsiz34kzlDzl82pzod21sjsy922jdSaq HTTP/1.1
Host: authenticatie.vlaanderen.be
Authorization: Bearer Pof334fjh983kdhsIS34djfe9ekfAzjdke72k5hdtzE

De authenticatie op het Authorization Endpoint gebeurt zonder gebruikersinteractie met de identiteit waarmee de gebruiker aangemeld is. Het Authorization Endpoint stuurt een Authorization Code terug naar de redirect URL.

Voorbeeld van het uitleveren van een Authorization Code:

GET /callback?
  code=OV9FU_1lxJoAbc&
  state=Fheue34eg2hjsdehfk839ed83azz HTTP/1.1
Host: mijntoepassing.vlaanderen.be

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