7.2. Authenticatie & autorisatie

Om gebruik te maken van de AOS-API dien je te beschikken over een AOS-systeemaccount. Met het systeemaccount haal je een access token op. In deze paragraaf wordt uitgelegd hoe dit werkt.

Voor de authenticatie en autorisatie (op basis van OAuth 2) moet een access token opgehaald worden met de volgende gegevens:

• onMicrosoftAccount: siviafdtooling
• UserFlow: B2C_1_ROPC_Auth
  

Dit is een ROPC-call, oftewel een Resource Owner Password Credential call, het betreft een POST method.

Schematische weergave van autorisatie-call

Met deze gegevens ziet de URI van de autorisatie server er als volgt uit:

• https://siviafdtooling.b2clogin.com/siviafdtooling.onmicrosoft.com/B2C_1_ROPC_Auth/oauth2/v2.0/token
  

Client-id

Om een access token te kunnen verkrijgen is een client-id nodig, dit client-id verschilt per SIVI-API en wordt door SIVI per e-mail verstrekt na aanmelding voor een SIVI-API. Indien dit client-id achteraf nogmaals benodigd is, kan dit aangevraagd worden via support@sivi.org.

Login credentials

De login credentials zijn de username en password zoals is aangemaakt voor het systeemaccount.

Een systeemaccount is een niet-persoonlijk AOS-account dat aangemaakt kan worden via AFD Online Samenstellen (zie hoofdstuk Aanmaken account en accountbeheer). Voor het aanmaken van het account dient een bedrijfsgebonden niet-persoonlijk e-mailadres te worden gebruikt. Bijvoorbeeld: service@bedrijfsnaam.nl. Het systeemaccount is alleen bedoeld om te gebruiken via de API’s.

Access token

De autorisatie-call haalt het JWT Bearer token op bij de identity provider. Dit token dient aan de URI van de API-call te worden toegevoegd. De access token dient met onderstaand POST commando te worden opgevraagd:

https://siviafdtooling.b2clogin.com/siviafdtooling.onmicrosoft.com/B2C_1_ROPC_Auth/oauth2/v2.0/token?username=<serviceaccount@bedrijfsnaam.nl>&password=<password>&grant_type=password&scope=openid+<Client-id>+offline_access&client_id=<Client-id>&response_type=token+id_token

Vervang hierbij de gegevens tussen de kleiner dan (<) en de groter dan (>) tekens. Let er hierbij op dat je die tekens zelf ook verwijdert.

Voorbeeld:

https://siviafdtooling.b2clogin.com/siviafdtooling.onmicrosoft.com/B2C_1_ROPC_Auth/oauth2/v2.0/token?username=service@sivi.org&password=12345&grant_type=password&scope=openid+ab12...-...-...789+offline_access&client_id=ab12...-...-...789&response_type=token+id_token

Waarbij ab12………789 staat voor het eerder verkregen client-id.

Deze call komt met het volgende (soortgelijke) antwoord:

{"access_token":"eyJ0eXAiOiJKV1QiLCJhbGci………hudgfWf2Te","token_type":"Bearer","expires_in":"3600",”refresh_token”: "abXZeXAiOiJKV1QiLCJhbGci………hudgfWf2Te",”id_token”: "eyJ0eXAiOiJKV1QiLCJhbGci………hudgfWf2Te"}

Waarbij de waarde van “access_token” de access token is die meegegeven moet worden aan de API van ophalen AFD definities. De waarde van “token_type” is altijd “Bearer”. De refresh token kan gebruikt worden om een hernieuwde access token te verkrijgen. De id token geeft de ID van de client aan, deze is niet nodig bij de aanroep van de API ophalen AFD-definities.

Geldigheidsduur

De waarde die teruggegeven wordt met “expires_in” geeft de geldigheidsduur van de access token in seconden. Deze staat momenteel ingesteld op 3600 seconden, oftewel 1 uur.

Het ophalen van een access token heeft een relatief lange verwerkingstijd, het is dus raadzaam om dezelfde access token te gebruiken tijdens de geldigheidsduur.

Refresh token

De refresh token wordt gebruikt om een nieuwe access token op te halen. De login credentials worden dan niet meer meegestuurd, maar alleen de client-id en de refresh token. De refresh token heeft ook een geldigheidsduur en deze staat momenteel ingesteld op 14 dagen. Echter na het ophalen van de access token met de refresh token wordt er een nieuwe refresh token teruggegeven, die dan weer 14 dagen beschikbaar is. Elke keer moet het meest recent verkregen refresh token worden gebruikt. Op de eerder gebruikte refresh token zit een detectie op ongeautoriseerd gebruik en die token kan dus eerder ongeldig gemaakt zijn. Na het verlopen van de refresh token (of als een refresh token ongeldig is gemaakt) moet een nieuwe access en refresh token worden opgehaald met de login credentials.

Authenticatie & autorisatieproces schematisch weergegeven

De autorisatie-call haalt het JWT Bearer token op bij de identity provider met de refresh token. De nieuwe tokens kunnen met onderstaand commando worden opgevraagd:

https://siviafdtooling.b2clogin.com/siviafdtooling.onmicrosoft.com/B2C_1_Afs_Mapping_Service_Auth/oauth2/v2.0/token?grant_type=refresh_token&client_id={@ClientId}&refresh_token={@RefreshToken}

Voorbeeld:

https://siviafdtooling.b2clogin.com/siviafdtooling.onmicrosoft.com/B2C_1_Afs_Mapping_Service_Auth/oauth2/v2.0/token?grant_type=refresh_token&client_id=ab123...789&refresh_token=rf456...77zz

Waarbij ab123…789 staat voor het client-id en rf456…77zz voor de refresh token.

Het response-bericht na aanroep met een refresh token ziet er als volgt uit:

{
    "access_token": "eyJ0eXAiOiJKV1Qi...p-Hy_YrFSiK2aDqA",
    "id_token": "eyJ0eXAiOiJKV1...fTariTFcD7oryEzKswIZvI-RNlxstg",
    "token_type": "Bearer",
    "not_before": 1654005373,
    "expires_in": 3600,
    "expires_on": 1654008973,
    "resource": "92345022-c862-40fa-b921-0711fe8e8b63",
    "id_token_expires_in": 3600,
    "profile_info": "eyJ2ZXIiOiIxLjAiLC...FjY291bnQifQ",
    "scope": "9234...8b63 offline_access openid",
    "refresh_token": "eyJraWQiOiJ...6vTptV4GTEi_IB2Yg",
    "refresh_token_expires_in": 1209600
}

In dit response-bericht staan de nieuwe access token en de nieuwe refresh token.

*Bekijk de website van Auth0 voor meer informatie over het gebruik van refresh tokens en Auth0.

Na het verkrijgen van het access token kan deze worden meegegeven in de servicecalls die in de volgende pararaaf zijn beschreven.