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.

...

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).

...

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.

...

• 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:

...

{
"iss": "3318",
"sub": "3318",
"aud": "https://beta.oauth.vlaanderen.be/authorization/ws/oauth/v2/token",
"exp": "1587979731",
"iat": "1587979431",
"jti": "19017aeb-3673-4f04-8ef7-e0756b80a667"
}

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 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:

...

POST https://beta.oauth.vlaanderen.be/authorization/ws/oauth/v2/token
Content-Type: application/x-www-form-urlencoded
User-Agent: PostmanRuntime/7.22.0
Accept: */*
Cache-Control: no-cache
Host: beta.oauth.vlaanderen.be
Accept-Encoding: gzip, deflate, br
Content-Length: 855
Connection: keep-alive

grant_type=client_credentials&scope=msg_statuses_v1_G%20msg_mailbox_v1_P%20msg_msg_v1_P&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiIzMzE4Iiwic3ViIjoiMzMxOCIsImF1ZCI6Imh0dHBzOi8vYmV0YS5vYXV0aC52bGFhbmRlcmVuLmJlL2F1dGhvcml6YXRpb24vd3Mvb2F1dGgvdjIvdG9rZW4iLCJleHAiOiIxNTk4NTMyOTQzIiwiaWF0IjoiMTU5ODUzMjY0MyIsImp0aSI6IjI2MWQ4NmQ4LTVhY2MtNGNiNS1hMGZkLWEyYTNkZDJmY2I5NCJ9.W5dEZa5RDZ1U250Sm65qkvd5bW6O1ZeZWW8W_RjfKcNg0hSAXOXdJKP8TXnFlqpWswhb8OGYMDS-6YcSVpyrV6roD3FyioPqpaxFkFe1xzanoF6KZTMYA4TTkYROMZkG1U166ZQf7y09S5CekeNzfGF9ORk1toEiROksVZa-inTe46ioJSdVzUf8t-IRXPWR-ucHO9A8IXEQ-dwCrzJ_f1dq24R8eZsiZmplx_nXtfQ9yXD3XPDu-NZiSLY0TKexqPdd4uvlrdzoFe6O8usMkhpBfsC3inUCzMfKT30rk1uJvvKH2s0iYpUp-FZCCn-0unWATwivWhMkvBEVZOWbGA

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.

...

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.

...

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.

...

POST https://.........................../api/v1/messages/messages
Authorization: Bearer POtyWHuQd94pk6AtHbew3B==

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.

...