Inleiding

Het aanbod van MAGDA werd begin 2020 uitgebreid met REST diensten. Voor deze REST diensten wordt gebruik gemaakt van een token-gebaseerd authenticatie systeem.
Token-gebaseerde authenticatie laat toe om authenticatie informatie naadloos te laten doorstromen van het ene systeem naar een andere. Ook multi-partijen scenario’s kunnen hiermee gemakkelijker ondersteund worden. Bijvoorbeeld een scenario met een resource server (MAGDA) die informatie (of resources) ter beschikking stelt, een opdrachtgever (de entiteit die de recht heeft om de informatie te raadplegen) en een leverancier (de entiteit die de opvraging uitvoert in naam van de opdrachtgever).

Definities

Een token is een stuk informatie dat kan gebruikt worden om een identiteit en/of een recht te representeren.
Tokens kunnen ofwel onleesbaar (opaque) of leesbaar zijn.
Opaque tokens zijn een niet interpreteerbaar, ruw stuk informatie. Om ze te gebruiken is er altijd een derde partij (meestal de autorisatie provider) nodig om te weten als het token geldig is of aan welke toegang of identiteit het token is gelinkt.
Leesbare tokens zijn tokens die informatie bevatten over identiteit en/of autorisatie. JSON Web Tokens (JWTs) zijn leesbare tokens.

Context

MAGDA maakt gebruik van de AIV Authenticatie en Autorisatie Server (AAS) voor het authentiseren en autoriseren van afnemers in het geval van token authenticatie.

Werken met tokens omvat twee fases:

1. Het krijgen van een access token van een authenticatie en autorisatie server

2. Het gebruiken van een access token om een oproep naar een resource server te doen (bv een MAGDA dienst)

De access tokens die uitgekeerd worden door de AIV AAS zijn opaque tokens. Tijdens het proces om ze te krijgen wordt er gebruik gemaakt van een JWT (aanvraag token).

Open

Stappen 1 en 2 maken deel uit fase 1: het krijgen van een access token.

Stappen 3 en 4 maken deel uit fase 2: het opvragen van MAGDA resource / diensten

Magda is ook de “resource server”.

Fase 0: Opzet bij de Token provider van de Vlaamse Overheid (AIV AAS)

Alvorens er gestart kan worden, dient de afnemer opgezet zijn bij de token provider van de Vlaamse Overheid (AIV AAS).

Wanneer dat gebeurd is, ontvangt de gemandateerde gebruiker het recht om de publieke sleutels te beheren bij AIV AAS.

Hij of zij dient dan de publieke sleutel van het certificaat dat gebruikt zal worden, 1-malig op te laden (via de user interface van AIV AAS).

Bijkomende informatie over hoe dat dient te geburen kan u vinden op: https://beta.oauth.vlaanderen.be/authorization/Help/Api/ClientCredentialsGrant

Fase 1: Het krijgen van een access token

Authenticatie en autorisatie aanvraag aanmaken

De afnemer stuurt een request met 1-Way SSL naar de AIV AAS om een access token te krijgen.

Deze request moet een aanvraag token bevatten. Dit aanvraag token is een JWT token. Dit procedure volgt de RFC 7523: “JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants”.

Dit token wordt getekend door de private key die overeenstemt met het VO DCB certificaat met een door MAGDA erkende Common Name. Deze Common Name krijgt de afnemer van MAGDA tijdens het aansluitingsproces.

Er zijn twee AA servers, een voor TNI en een andere voor productie:

• TNI: https://beta.oauth.vlaanderen.be/authorization/ws/oauth/v2/token

• PROD: https://oauth.vlaanderen.be/authorization/ws/oauth/v2/token

JWT token aanmaken

Het JWT aanvraag token moet het volgende bevatten:

Voorbeeld:

Tekenen van het JWT token

Het JWT aanvraag token voor de access token aanvraag moet getekend zijn met de private key die overeen stemt met het VO DCB certificaat. Tekenen van JWT volgt de JWS standard (RFC 7515).

De AIV AAS ondersteunt de “x5c”, “x5u”, “jwk”, “jku” eigenschappen van JWS niet. Dit betekent dat het certificaat dat gebruikt wordt om te tekenen, niet bij het token mag zitten. De public key van het certificaat moet op voorhand opgeladen worden door de afnemer in Geosecure. Dit kan via de volgende link: https://beta.oauth.vlaanderen.be/admin/ (voor TNI) en https://oauth.vlaanderen.be/admin (voor Productie). Hier kan je bij de desbetreffende OAuth client via de link 'Client certificaat toevoegen' de publieke sleutel van je VO-DCB certificaat opladen.

De getekende JWT moet in de “client_assertion”.

Aanvraag HTTP request

De request moet een HTTP POST request zijn met x-www-form-urlencoded parameters. De volgende parameters moeten ingevuld worden:

• “grant_type”: “client_credentials”

• “scope”: moet ingevuld worden met een lijst van scopes waaraan het access token toegang gaat geven. Er wordt een scope per dienst gebruikt. Dus voor elke MAGDA dienst die men wil aanroepen, moet hier de nodige scope aangevraagd worden. “scopes” worden door middel van een spatie van elkaar afgescheiden.

  • Indien uw MAGDA aansluiting gebruik maakt van een hoedanigheidscode, dient u ook een scope toe te voegen waarmee u aangeeft welke de hoedanigheidscode is van de hoedanigheid waarin u wenst bediend te worden. Dit doet u door een scope toe te voegen: HDC_xxx (waar xxx de hoedanigheidscode is).

• “client_assertion_type”: “urn:ietf:params:oauth:client-assertion-type:jwt-bearer”

• “client_assertion”: het JWT token beschreven in het vorige punt

Voorbeeld:

Antwoord van de Authenticatie en Autorisatie Server (AAS)

Als de authenticatie aanvraag correct verlopen is, krijgt de aanvrager een JSON payload terug met het access token.

De eigenschap “access_token” bevat het token voor de call naar elke MAGDA REST dienst (resource).

Access tokens worden uitgereikt met een bepaalde levensduur. Die levensduur wordt meegeven in het “expires_in” veld (uitgedrukt in seconden). Momenteel bedraagt die 16 uur, maar het staat onze token provider vrij dit interval eenzijdig aan te passen.

We raden aan om een token maximaal te hergebruiken en pas kort voor het einde van haar levensduur, een nieuw exemplaar aan te vragen. Dit verlaagt immers de load naar onze token provider. Bovendien vermijdt u op die manier dat onze token provider u geen tokens meer zal toekennen (momenteel ligt die grens op maximaal 2000 token bevragingen per uur per afnemer).

Wanneer u een token gebruikt waarvan de levensduur verstreken is, zal u van MAGDA een 401 UNAUTHORIZED fout terug krijgen. U zal dan een nieuw token moeten aanvragen om verdere requests naar MAGDA te kunnen uitvoeren.

Code voorbeeld

In de volgende voorbeelden wordt er van Apache Http Components (HttpClient) gebruik gemaakt om de HTTP Call uit te voeren en van jose4j voor het aanmaken van de JWT. Andere libraries zullen op een gelijkaardige manier werken.

Voor C# verwijzen we naar deze .

Het bouwen van de getekend JWT met jose4j:

Voor het aanmaken van een HttpClient http request:

Daarna kan de request verstuurd worden:

Als het request correct is, antwoord de AAS met een antwoord zoals beschreven in 4.2

Fase 2: Het opvragen van Magda resource

Authenticatie

Voor elke MAGDA resource “request” is een geldig access token nodig, dat de afnemer in Fase 1 verkregen heeft.

Het access token wordt meegegeven in de “Authorization” HTTP header. De token wordt voorafgegaan door de prefix “Bearer “.

Maximal Load

Om een maximale dienstverlening te kunnen garanderen gebruikt Magda throttling. Bij een overtreding tegen 1 van de 4 onderstaande regels: zal MAGDA dan ook een 429 response geven:

• Maximum calls per domein: 18000 transacties per minuut

• Maximum calls per dienst: 2400 transacties per minuut

• Maximum calls per afnemer: 1800 transacties per minuut

• Maximum calls per afnemer per dienst: 1800 transacties per minuut

Antwoord signing

MAGDA tekent alle haar antwoorden met het eigen MAGDA certificaat.

Het antwoord van MAGDA wordt met het MAGDA certificaat getekend. Bijvoorbeeld: keyId=”magda-response-signing-key”.