Skip to main content Link Menu Expand (external link) Document Search Copy Copied

Authenticatie via OAuth2 Client Credentials voor KIK-Inzage

OAuth (Client Credentials Private Key JWT)

De Kadaster autorisatie en authenticatie dienst ondersteunt het ontsluiten van de Kadaster services op basis van de OAuth 2.0 Client Credentials specificatie. De client authenticatie is hierbij gebaseerd op het JSON Web Token (JWT) Profile. 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.

In het gebruik van deze usecase speelt de authenticatie van een klant organisatie een cruciale rol. De client van een klant organisatie dient zich te authenticeren middels een Signed JWT waarbij de ondertekening met een PKIoverheid certificaat uitgevoerd moet worden waarin het Organisatie-identificatienummer (OIN) is opgenomen. Zie over het OIN: OIN Stelsel - Logius handreiking.

Dit document biedt een handleiding voor het aansluiten op de KIK-Inzage API met behulp van OAuth2 Client Credentials.

Inhoudsopgave

Machine to machine

De API wordt gebruikt door een geautomatiseerd proces.

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.

Technische werking OAuth2 CC

OAuth2 CC

Legenda:

  • ‘Token Server’ is de Kadaster OAuth2 Server
  • ‘Resource Server’ is de Kadaster KIK-Inzage API serviceaanbieder
  • ‘Client’ is de serviceafnemer die met Kadaster KIK-Inzage direct communiceert
  • ‘Issuer’ is de service die het JWT ondertekent met het eindklant PKIoverheid certificaat
    Het kan ook zijn dat de ‘Client’ en de ‘Issuer’ dezelfde zijn.

Voor verschillende scenario’s uitwerking, zie verder ‘‘OAuth2 Client Credentials usecases-integratie’ omschrijving

Voor de KIK-Inzage API kennen we 2 externe omgevingen: de productieomgeving en de externe testomgeving (ETO).

Voor de realisatie van de OAuth2 Client Credential flow zijn de volgende stappen nodig:

Client Applicatie aanmelden

Client applicatie aanmelden bij het Kadaster. Dit moet éénmalig per client applicatie gedaan worden. De client service krijgt een client_id.
Eén ‘client service’, de service die met Kadaster KIK-Inzage direct communiceert, kan voor meerdere PKIoverheid eindklant certificaten gebruikt worden.

JWT client assertion

Om een access token te verkrijgen dient een JWT (client assertion) samengesteld te worden welke met het PKIoverheid certificaat van de organisatie (eindklant) wordt ondertekend. Ter controle van de ondertekening van het JWT dient een JWKS URI met het publieke certificaat beschikbaar gesteld te zijn.
Het PKIoverheid certificaat moet onderdeel zijn van de hiërarchie: Staat der Nederlanden Private Root CA - G1, Domain Private Services: Staat der Nederlanden Private Services CA - G1, zie: (https://cert.pkioverheid.nl/){:target=”_blank” rel=”noreferrer”}
Tevens dient het Organisatie-identificatienummer (OIN) te zijn opgenomen in het subject. Dit OIN behoort in de Kadaster klant registratie bij één klant bekend te zijn.

JWSAlgorithm.RS256 Validatie van het JWT wordt gedaan aan de hand van de ondertekening (signature) en de volgende claims worden geverifieerd:

  • iss (issuer): moet gelijk zijn aan het client_id
  • aud *(audience): moet gelijk zijn aan het authorization server token endpoint (zonder protocol, inclusief port): authorization.kadaster.nl:443/auth/oauth/v2/token
  • sub (subject): moet gelijk zijn aan het client_id
  • exp (expiry time): moet in de toekomst liggen (een korte expiry van enkele minuten is aanbevolen)
  • jti (jwt id): wordt gecached tot de expiry time en hierop wordt replay attack protection uitgevoerd (een JWT kan dus slechts eenmalig worden gebruikt!)

Voorbeeld JWT claims:

header:

 {
   "typ": "JWT",
   "alg": "RS256",
   "kid": "<the key_id from the jwks>"
 }

payload:

 {
   "iss": "<client_id>",
   "sub": "<client_id>",
   "aud": "authorization.kadaster.nl:443/auth/oauth/v2/token",
   "exp": 1645632001,
   "nbf": 1645628101,
   "iat": 1645628401,
   "jti": "e43cf74c-d278-4b34-8d49-b08e7a52b216"
 }

Ondertekening van het JWT wordt gedaan met JWSAlgorithm RS256 conform: RSASSA-PKCS-v1_5 met SHA-256 hash algorithm rfc7519.

JWT client assertion validatie

de De ondertekening (signature) van het JWT wordt door het Kadaster gecontroleerd met behulp van het bij de client geconfigureerde endpoint voor de JSON Web Key Set, de zogenoemde JWKS URI, waarmee de JWKS wordt opgehaald.

De JWKS URI is een endpoint dat alle PKIoverheid publieke deel eindklant-certificaten publiceert. Kadaster gebruikt dit endpoint om de ondertekende JWT’s te valideren. Met behulp van een JWKS endpoint wordt ook het beheer-mechanisme van de PKIoverheid certificaten ondersteund. Bijvoorbeeld: er kunnen meerdere versies van een eindklant PKIoverheid certificaat gepubliceerd worden.


De kid (key-id) in de header van het JWT geeft aan met welke key de ondertekening is uitgevoerd en komt overeen met een kid in het JWKS. Het gebruikte certificaat zal worden gecontroleerd op geldigheid en zal onderdeel moeten zijn van de PKIoverheid chain en moet het OIN in de Kadaster klant registratie zijn opgenomen.
Om deze chain te kunnen controleren dient de x5c parameter onderdeel te zijn van de JWK. De inhoud van de x5c parameter kan met CSR Decoder and Certificate Decoder gecontroleerd worden op juistheid:

Issuer moet voorkomen als een van de TSP-certificaten onder Domein Private Services: Staat der Nederlanden Private Services CA - G1 op
Overzicht PKIoverheid certificaten. In het Subject moet als serialNumber het OIN van de organisatie staan.

Zie voor JWK: rfc7517

Voorbeeld JWKS:

 {
   "keys": [
     {
       "alg": "RS256",
       "e": "AQAB",
       "n": "<...cut her for readability...>-gTlQ",
       "kty": "RSA",
       "kid": "oude_nog_geldige_key",
       "x5c": [
                "MIIG<...cut her for readability...>TbQjZh0i"
            ]
     },
     {
       "alg": "RS256",
       "e": "AQAB",
       "n": "<...cut her for readability...>-gTlQ",
       "kty": "RSA",
       "kid": "nieuwe_ook_geldige_key",
       "x5c": [
                "MIIG<...cut her for readability...>TbQjZh0i"
            ]
     }
   ]
}

Access token opvragen

De access token geeft toegang tot de KIK-Inzage API.

De client kan vervolgens met het JWT client assertion een access token opvragen door een http POST naar het token endpoint met de juiste headers en content te sturen:
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:

grant_type=client_credentials&scope=<scope(s)&client_assertion=<jwt assertion>&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer

Het token Kadaster endpoint zal hierop het JWT client assertion valideren en een response geven met daarin het access token.

response

{
    "access_token": "9e25ab45-82a4-4f9e-8bf6-b9ef0eb7568e",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "kik-inzage"
}

Dit access 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

Een voorbeeld van een API call met access token via curl.

curl
--header 'Authorization: Bearer 9e25ab45-82a4-4f9e-8bf6-b9ef0eb7568e'
https://api.brkinzage.kadaster.nl/kik-inzage/v6

Access token opnieuw opvragen

Het access token is 1 uur geldig. Als het access token verlopen is, dan kan weer een nieuw access token opgevraagd worden zoals beschreven onder ‘Access token opvragen’.

Voorbeeld code JWT genereren

Voorbeeld code voor het genereren van JWKS en JWT in Java is beschikbaar op KikInzageOauth_CC_JWT_Example.