Identity API

De Identity API maakt authenticatie mogelijk voor gebruikers en applicaties die gebruik willen maken van API’s van ANVA. We bieden een identity provider oplossing gebaseerd op OAuth 2.0 en OpenID Connect. Naast het benaderen van de API’s maakt onze OpenID Connect identity provider ook integratie en single sign-on in andere applicaties mogelijk.

De OpenID Connect identity provider biedt ondersteuning voor diverse grant types. Afhankelijk van de toepassing is een bepaald grant type meer of minder geschikt. De grant types die worden ondersteund zijn de ‘authorization code grant’, ‘client credential grant’, ‘implicit grant’ en ‘refresh token grant’.

De authorization code grant is aan te bevelen voor websites en applicaties waar gebruikers zelf acties uitvoeren en gebruik wordt gemaakt van onze API’s. De gebruiker logt zelf met zijn accountgegevens in bij de OpenID Connect identity provider waarbij de client applicatie zelf niet over deze accountgegevens hoeft te beschikken. Als gebruik wordt gemaakt van de authorization code grant, dan wordt ook een refresh token verstrekt. Op basis van de refresh token grant kan een nieuw access token worden verkregen nadat geldigheid van de vorige is verstreken.

De client credential grant is aan te bevelen voor applicaties die vanuit bepaalde (batch)processen onze API’s raadplegen waarbij het niet van belang is dat de acties uit naam van specifieke gebruiker worden uitgevoerd.

We bieden ook ondersteuning voor de implicit grant, maar het gebruik hiervan is inherent kwetsbaarder dan het gebruik van de authorization code grant, omdat het access token via de URI gedeeld wordt met de client applicatie in plaats van in een versleutelde HTTPS body.

De authorization code grant bestaat uit het uitvoeren van een autorisatie request waarmee een autorisatie code opgevraagd wordt. Vervolgens kan met de autorisatie code een token request worden uitgevoerd waarmee een access token opgevraagd wordt.

Autorisatie request

De autorisatie request kan op de onderstaande wijze worden samengesteld. De opgevraagde autorisatie code zal maximaal 10 minuten geldig zijn.

Endpoint: /identity/authorize
Method: GET
Query Parameters: De volgende parameters dienen in de request opgenomen te worden.

1. 1. client_id– Het client id van de OpenID Client.
   2. redirect_uri– Een geldige redirect URL van de client applicatie die tevens geregisteerd is bij de OpenID Client.
   3. response_type– De waarde ‘code’ moet gebruikt worden voor de authorization code grant.
   4. scope– Aan deze parameter moeten de gewenste autorisatie rollen worden toegevoegd. De rollen worden met een spatie van elkaar gescheiden. De rollen moeten tevens zijn geconfigureerd bij de OpenID Client.
   5. state– Een door de client applicatie uitgegeven waarde die bij ontvangst van de response gecontroleerd kan worden.
   6. nonce– Een door de client applicatie uitgegeven unieke waarde waaraan de specifieke response herkend kan worden.
   7. max_age– Een optionele parameter waarmee de client applicatie de maximale levensduur van het token kan beheren, waarbij geldt dat de maximale levensduur van het access token zoals geconfigureerd in de OpenID Client niet overschreden kan worden.
   8. response_mode– Een optionele parameter waarmee de client applicatie kan sturen in welk formaat de response wordt gegeven. De waarde ‘query’ (default) zorgt voor het opnemen van de response parameters in de query string van de response. De waarde ‘fragment’ zorgt voor het opnemen van de response parameters in de fragment string van de response.

Voorbeeld van request:

/identity/authorize?response_type=code

&scope=openid Basic
&client_id=92c0a4eb-40be-42a6-9f50-597c86666b7b
&state=Clientapp_XYZ
&redirect_uri=https://clientapp.nl/redirect
&nonce= mgEy0yLZ825W
&max_age=28800
&response_mode=query

Voorbeeld van response:
https://clientapp.nl/redirect?code=o3ztCK3W8kQxwpts&state= Clientapp_XYZ

Token request

De token request kan op de volgende manier worden samengesteld.

Endpoint: /identity/token
Method: POST
Headers: De volgende parameters moeten in de header van de request worden opgenomen.

1. Authorization– Basic authorisatie gevolgd met de Base64-encoded string van het Client ID en Client Secret van de OpenID Client. Het Client ID en Client secret verbinden met “:” en het geheel base64 coderen: base64encode([Client ID]:[Client secret])

Voorbeeld:
‘Authorization’:‘Basic’ OTJjMGE0ZWItNDBiZS00MmE2LTlmNTAtNTk3Yzg2NjY2YjdiOlBiZGtPSmJ0WGpWVktMQ2hFY2ZybGZ2RFlYUlZ4Vw’

2. Content Type– application/x-www-form-urlencoded

Voorbeeld:
‘Content-Type’:’application/x-www-form-urlencoded’

Request Body: De volgende parameters moeten in de body van de request worden opgenomen.

1. 1. grant_type– Bevat de waarde ‘authorization_code’.
   2. redirect_uri– De redirect URI van de client applicatie.
   3. code– De eerder verkregen autorisatie code.

De refresh token grant kan gebruikt worden om op basis van een eerder verkregen refresh token een nieuw access token op te vragen. De token request op basis van de refresh token grant kan op de volgende manier worden samengesteld.

Endpoint: /identity/token
Method: POST
Headers: De volgende parameters moeten in de header van de request worden opgenomen.

1. Authorization– Basic authorisatie gevolgd met de Base64-encoded string van het Client ID en Client Secret van de OpenID Client.

Voorbeeld:
‘Authorization’:‘Basic      OTJjMGE0ZWItNDBiZS00MmE2LTlmNTAtNTk3Yzg2NjY2YjdiOlBiZGtPSmJ0WGpWVktMQ2hFY2ZybGZ2RFlYUlZ4Vw’

2. Content Type– application/x-www-form-urlencoded

Voorbeeld:
‘Content-Type’:’application/x-www-form-urlencoded’

Request Body: De volgende parameters moeten in de body van de request worden opgenomen.

1. 1. grant_type– Bevat de waarde ‘refresh_token’.
   2. refresh_token– Het eerder verkregen refresh token.

Deze methode van authenticatie kan worden gebruikt buiten de context van een gebruik om, bijvoorbeeld bij interactie tussen twee systemen waarbij het niet van belang is dat de handelingen uit naam van een gebruiker worden uitgevoerd.

De token request kan op de volgende manier samengesteld worden.

Endpoint: /identity/token
Method: POST
Headers: De volgende parameters moeten in de header van de request worden opgenomen.

1. Authorization– Basic authorisatie gevolgd met de Base64-encoded string van het Client ID en Client Secret van de OpenID Client.

Voorbeeld: ‘Authorization’:‘Basic OTJjMGE0ZWItNDBiZS00MmE2LTlmNTAtNTk3Yzg2NjY2YjdiOlBiZGtPSmJ0WGpWVktMQ2hFY2ZybGZ2RFlYUlZ4Vw’

2. Content Type– application/x-www-form-urlencoded

Voorbeeld: ‘Content-Type’:
‘application/x-www-form-urlencoded’

Request Body: De volgende parameters moeten in de body van de request worden opgenomen.

1. 1. grant_type– Bevat de waarde ‘client_credentials’.
   2. scope– Aan deze parameter moeten de gewenste autorisatie rollen worden toegevoegd. De rollen worden met een spatie van elkaar gescheiden. De rollen moeten tevens zijn geconfigureerd bij de OpenID Client. Tevens moet aan deze parameter het organisatie ID worden toegevoegd.

Voorbeeld orgId:
‘scope’:’Basic orgId:7e6bb160-91d9-4093-bc50-9699d446e774′

Voorbeeld orgCode:
‘scope’:’Basic orgCode:organisatiecode′

Access tokens die via de OpenID Connect methode worden gegenereerd, hebben een bepaalde levensduur. Deze levensduur van het access token kan worden geconfigureerd in de OpenID Client op ANVA Hub. Als een token nog geldig is, dan is het de bedoeling (fair use) om dit token bij volgende requests naar de api’s van ANVA Hub (zoals de XML module) te hergebruiken, tot het moment waarop het access token niet meer geldig is. Vanaf dit moment kan uiteraard weer een nieuw access token worden opgevraagd via de OpenID Connect methode. Het is dus niet wenselijk om voor iedere request naar een api op ANVA Hub eerst een nieuw access token op te vragen.

Voor meer informatie over het gebruik en de samenstelling van requests en responses kunt u hier de OpenID Connect specificaties raadplegen.

Partner document v1.14.pdf