SYVAS Autorisatie en toegang Mededelingen in de ETO omgeving Praktijktest

Binnen SYVAS moet een gebruiker één of meerdere rollen hebben. Voor de SYVAS API is de rol Aanbieder M2M van belang. Deze rol dient gekoppeld te zijn aan het gebruikte MijnKadaster account.

Kadaster maakt gebruik van een autorisatieportaal met de naam GAA (Generieke Authenticatie en Autorisatie). Inloggen op dit portaal gebeurt d.m.v. OAuth2. Vervolgens dient het portaal als doorgeefluik richting de backend van SYVAS.

De volledige interactie tussen de interne en externe systemen zien er als volgt uit:

Rollen in SYVAS

OAuth2

Voor autorisatie en toegang tot SYVAS maken we gebruik van de OAuth 2.0 Authorization Code specificatie. Hierbij worden de NL-gov overheidsstandaarden gevolgd, zoals beschreven op NL GOV Assurance profile for OAuth 2.0 v1.0 en NL GOV Assurance profile for OpenID Connect 1.0.

Deze flow bestaat uit het ophalen van een autorisatie code waarna deze kan worden ingewisseld voor een access token. Met het access token kan een applicatie vervolgens de SYVAS API aanroepen.

De interactie tussen de Client applicatie (NSL), gebruiker (Notaris), de Autorisatie Server en Kadaster API (SYVAS) ziet er als volgt uit:

OAuth2 interactie

Authorisatie flow gebruiker/gebruiker client

Naast de autorisatie van de client door middel van de client credentials moet er authenticatie van de gebruiker plaatsvinden. En moet de gebruiker éénmalig toestemming geven voor het gebruik van zijn gebruikersaccount met de scope(s) door de betreffende client. Dit proces doorloopt de volgende stappen:

Als eerste krijgt de gebruiker de keuze tussen inloggen met een Mijn Kadaster account of met eHerkenning:

Inlogkeuze

Afhankelijk van de gekozen methode verschijnt daarna één van de volgende twee inlogschermen:

Inloggen via Mijn Kadaster
Inloggen via eHerkenning

Na het inloggen verschijnt onderstaand scherm:

Toestemming geven

De gebruiker geeft via een GRANT toestemming aan de client om met de identiteit van de gebruiker de getoonde scope(s) te gebruiken. Dit is noodzakelijk om de client te laten functioneren.

Technische Werking

Bij elk request naar een API endpoint moet een access token in de header van het request meegestuurd worden. Om dit token te verkrijgen moeten onderstaande stappen doorlopen worden.

  1. Client Applicatie aanmelden. Dit moet éénmalig per client applicatie gedaan worden.

  2. Authorization code opvragen, de client dient gebruik te maken van PKCE. De gebruiker moet hierbij inloggen en de client consent geven om uit naam van de gebruiker API’s te mogen bevragen.

  3. Access token opvragen. Dit token geeft toegang tot de API. Dit token is één uur geldig en zal daarna ververst moeten worden.

  4. Access token verversen dmv het refresh token. Als het access token verlopen is kan deze ververst worden. Daarvoor hoeven stap 1 t/m 3 niet opnieuw doorlopen te worden. Indien het refresh token niet meer geldig is, zal de authorization code flow opnieuw moeten worden doorlopen (vanaf stap 2).

OAuth2 stappen

Authorization code opvragen

(Flow stap 1,2,3,4,5)

Een client kan een authorization code opvragen door een gebruikers sessie via een redirect naar het authorization endpoint te leiden. De client dient hierbij gebruik te maken van Proof Key for Code Exchange (PKCE rfc7636 ) Een dergelijke aanroep dient er als volgt uit te zien:

redirect
HTTP/1.2 302 Found

Header Location:

https://authorization.kadaster.nl/auth/oauth/v2/authorize?response_type=code&client_id=[client_id]&state=[state]&scope=[scopes]&redirect_uri=[redirect_uri]&nonce=[nonce]&code_challenge=[your-code-challenge]&code_challenge_method=S256

code_verifier = high-entropy cryptographic random STRING using the unreserved characters [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~" , with a minimum length of 43 characters and a maximum length of 128 characters

code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

Op het authorization endpoint moet een gebruiker zich authenticeren en consent geven voor zijn user en noodzakelijke scopes(zie Authorisatie flow gebruiker/gebruiker client). De gebruiker wordt daarna doorgestuurd naar de redirect_uri zoals aangegeven in de aanroep. Uit de request parameters kan door de client applicatie de authorization code gehaald worden. Bijvoorbeeld:

http://localhost:14057/authorize/?&state=[state]&code=42283687-7c09-4018-8a7a-9e9533366dbb

Het authorization code is 30 seconden geldig.

Access token opvragen

(Flow stap 6,7)

De client kan vervolgens met het client id (, client secret), authorization code en de code_verifier een access token opvragen door een post uit te voeren op het token endpoint met de juiste headers en content:

request (POST) - confidential client
URL: https://authorization.kadaster.nl/auth/oauth/v2/token
Header: Geef in de header als ContentType application/x-www-form-urlencoded mee.
Body: De parameters moeten in de body meegegeven worden. Zie voorbeeld:

grant_type=authorization_code&code=[authorisation_token]&client_id=[client_id]&client_secret=[client_secret]&code_verifier=[code_verifier]&redirect_uri=[redirect_url]

request (POST) - public client
URL: https://authorization.kadaster.nl/auth/oauth/v2/token
Header: Geef in de header als ContentType application/x-www-form-urlencoded mee.
Body: De parameters moeten in de body meegegeven worden. Zie voorbeeld:

grant_type=authorization_code&code=[authorisation_token]&client_id=[client_id]&code_verifier=[code_verifier]&redirect_uri=[redirect_url]

Het token endpoint zal hierop een response geven met daarin een access token en een refresh token.

response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "access_token": "7ce2***-****-****-****-********20b6",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "03e7***-****-****-****-********3235",
  "scope": "syvas.cto.aanbieden.verzoeken"
}

Dit access token en refresh token moet door de client applicatie op een veilige manier bewaard worden. Het access token moet meegestuurd worden bij elke call naar de API.

Access token gebruiken

(stap 8,9,10,11)

Een voorbeeld van een API call met het access_token:

GET https://or.kadaster.nl/inschrijving-eto/service/aanbiedenverzoeken/v1/aanbiedenVerzoeken.wsdl
Authorization: Bearer 4703***-****-****-****-********38f7

Dit geeft de volgende response:

HTTP/1.1 200 OK
Content-Type: text/xml

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<wsdl:definitions>
...
</wsdl:definitions>

Access token verversen

Het access token is 1 uur geldig. Als het access token verlopen is dan kan een nieuw access token en refresh token opgevraagd worden.

request (POST)
URL: https://authorization.kadaster.nl/auth/oauth/v2/token
Header: Geef in de header als ContentType application/x-www-form-urlencoded mee.
Body: De parameters moeten in de body meegegeven worden. Zie voorbeeld:

client_id=[client_id]&client_secret=[client_secret]&grant_type=refresh_token&refresh_token=[refresh_token]

response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "access_token": "87a6***-****-****-****-********40c0",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "e31f***-****-****-****-********0e64",
  "scope": "syvas.cto.aanbieden.verzoeken"
}

Oauth instellingen

value lifetime (sec) duur

authorization token

300

5 min

access token

3600

1 uur

refresh token

604800

7 dagen
property value toelichting

max_oauth_token_count

1

token per client/resource owner

reuse_refresh_token

false

new refresh tokens are issued

reuse_refresh_expiration

false

new expiration date is set

Met ingang van 1 juli 2024:

property value toelichting

max_oauth_token_count

1

token per client/resource owner

reuse_refresh_token

false

new refresh tokens are issued

reuse_refresh_expiration

true

new expiration date is set (geen nieuwe expiratie, oorspronkelijk eindtijd blijft geldig (7 dagen))

Naslag en gebruikte links