Blauwe Knop Connect

De verschillende typen berichten in dit protocol zijn:

• App Manager Certificate JWT: Het Verifiable Credential uitgegeven door de App Manager (beschreven in sectie Verifiable Credentials)
• Challenge Response JWT: De JWS waarin de App de nonce ondertekent (beschreven in sectie Verifiable Presentation)
• Self-Signed Certificate JWT: De zelf-ondertekende JWS gebruikt wanneer nog geen identiteitsinformatie is uitgewisseld

Het CreateSession protocol ziet er in een sequence diagram als volgt uit:

In de sequence diagrams worden de volgende termen gebruikt:

• EC (Elliptic Curve): Verwijst naar elliptic curve cryptografie, zoals gespecificeerd in de cryptografie sectie. Alle sleutelparen in het protocol gebruiken elliptic curve algoritmen.
• Root keypair: Het hoofdsleutelpaar van een organisatie of app, dat wordt gebruikt voor langdurige identificatie en wordt geregistreerd bij de stelselbeheerder.
• Ephemeral keypair: Een tijdelijk sleutelpaar dat wordt gegenereerd voor een specifieke sessie en na gebruik wordt weggegooid. Dit biedt forward secrecy - oude communicatie blijft veilig zelfs als het root keypair wordt gecompromitteerd.

De App initieert het CreateSession protocol door een sessie-aanvraag te sturen naar de Verifier.

De App vraagt een nieuwe challenge op met een HTTP POST request zonder body naar /v1/challenge.

De Verifier genereert met een cryptographically secure pseudorandom number generator (CSPRNG) een nonce bestaande uit minimaal 16 willekeurige bytes.

De Verifier antwoordt op het HTTP request van de App uit stap 2 met een JWS, ondertekend met zijn private key, en met de volgende claims:

• sub: een string die de waarde "challenge" MOET hebben.
• nonce: de nonce uit Stap 4, Base64-encoded.
• ephemeral_organization_ec_public_key: de Base64-encoding van de DER-encoded public key van de verifier.

De JWS MAG een kid header gebruiken om de public key aan te duiden waarmee de JWS geverifieerd moet worden.

Voorbeeld:

{
  "typ": "jwt",
  "alg": "ES256",
  "kid": "1"
}
.
{
  "sub": "challenge",
  "nonce": "BZpwbYf2TIYxvJEQY2FtAg==",
  "ephemeral_organization_ec_public_key": "MFkw....Wzhw=="
}

De App:

• Controleert dat de root organization EC public key van een ondersteund algoritme en curve is en dat hij geldig is (de coördinaten refereren naar een bestaand element van de elliptic curve).
• Verifieert de JWS van de Verifier uit bovenstaande stap met de root organization EC public key.
• Controleert dat de JWS een sub veld met waarde challenge bevat.
• Controleert dat de ephemeral organization EC public key van een ondersteund algoritme en curve is en dat hij geldig is.

De App genereert met een CSPRNG een nieuwe willekeurige AES key van de juiste grootte (128 bits in het geval van AES128 en 256 bits in het geval van AES256).

De App maakt het Verifiable Presentation als in de "Verifiable Presentation" sectie hierboven, en versleutelt deze middels ECDH-ES in de vorm van een JWE naar de ephemeral organization EC public key van de Verifier.

De App stuurt middels een HTTP POST naar /v1/complete het volgende JSON object naar de Verifier:

• nonce: de nonce die de Verifier eerder aanleverde.
• encrypted_challenge_result: de Verifiable Presentation JWE uit de vorige stap.

Voorbeeld:

{
    "nonce": "BZpwbYf2TIYxvJEQY2FtAg==",
    "encrypted_challenge_result": "eyBLyPjsJZs...5Y2tNYLRui"
}

De Verifier MOET de Verifiable Presentation verifiëren als in de "Verifiable Presentation" sectie hierboven.

De Verifier genereert met een CSPRNG een willekeurige alfanumerieke session token die minimaal 22 karakters MOET zijn (zodat hij minimaal 128 bit entropie heeft).

De App voert een GET uit op de request_uri van de Verifier:

GET /request_uri HTTP/1.1

De Verifier genereert de Request Object JWS, met daarin de volgende velden in de payload:

• client_id: URL die de Verifier identificeert.
• response_uri: URL waarnaar de App het Authorization Response dient te sturen.
• nonce: een willekeurige string gebruik makend van de URL-safe Base64 karakterset, genereerd met een CSPRNG, die minimaal 22 karakters MOET zijn (zodat hij minimaal 128 bit entropie heeft).
• client_metadata: JSON object met een jwks veld erin, met een keys veld daarin die de ephemeral verifier encryption public key uit Stap 2 bevat, als per RFC 7591 en RFC 7517.

De Verifier MAG een kid veld opnemen in de JWS header om aan te duiden met welke public key de JWS geverifieerd moet worden.

Voorbeeld:

{
  "typ": "jwt",
  "alg": "RS256",
  "kid": "1",
}
.
{
  "response_type": "vp_token",
  "response_mode": "direct_post.jwt",
  "client_id_scheme": "pre-registered",
  "client_id": "https://organization.example.com",
  "response_uri": "https://organization.example.com/response_uri",
  "scope": "nl.vorijk.oauth_scope.blauwe_knop.vp",
  "nonce": "L9E4aGM9ZzhhC7WLVxa1XKOzie7bzKh0",
  "client_metadata": {
    "jwks": {
      "keys": [{
        "kty": "EC",
        "crv": "P-256",
        "alg": "ECDH-ES",
        "use": "enc",
        "x": "GD006BBz6L9x1cQZQtihWeL_CBcJqjMerlFhGNHt6q8",
        "y": "dUCZyFZXdDNDTC_mRRveNtY_qT8D-LCDGoaNwE8i8rU"
      }]
    }
  }
}

De Verifier antwoordt het GET request uit stap 1 met bovenstaande JWS als volgt:

HTTP/1.1 200 OK
Content-type: application/oauth-authz-req+jwt

eyJhb...x5Nz-g

Gegeven het Verifiable Credential produceert de App een Verifiable Presentation per de "Verifiable Presentation" sectie hierboven. Vervolgens plaatst de App de Verifiable Presentation in het vp_token veld in de Authentication Response, samen met de ephemeral app encryption public key.

Voorbeeld:

{
  "vp_token": {
    "vc": "eyJjc....5TRSJ9",
    "disclosure": "eyJjc....f7B-q2"
  },
  "presentation_submission": {
    "id": "nl.vorijk.presentation_submission.blauwe_knop",
    "definition_id": "nl.vorijk.presentation_definition.blauwe_knop",
    "descriptor_map": [
      {
        "id": "nl.vorijk.descriptor_map.blauwe_knop",
        "format": "jwt",
        "path": "$",
        "path_nested": {
          "format": "jwt",
          "path": "$.vc"
        }
      }
    ]
  },
  "jwks": {
    "keys": [{
      "kty": "oct",
      "alg": "A128KW",
      "k": "GawgguFyGrWKav7AX4VKUg"
    }]
  }
}

Hierin MOET presentation_submission altijd bovenstaande waarde hebben, per § 6.1 van OpenID4VP. Dit geeft aan de Verifier aan waar deze het Verifiable Credential kan vinden binnen de ontvangen Verifiable Presentation.

Het jwks veld hierin maakt het mogelijk voor de app om een AES encryption key te versturen waarmee de app en de gebruikende applicatie data op applicatieniveau kunnen versleutelen, wanneer ze verkeer naar elkaar sturen nadat de OpenID4VP-sessie is afgerond. Dit is een toevoeging van deze standaard en niet gedefinieerd in OpenID4VP. De JSON-structuur van het jwks veld is gedefinieerd in RFC 7591 en RFC 7517 en net als in het Request Object. Bovenstaand voorbeeld maakt gebruik van de A128KW waarde voor alg, als gedefinieerd in § 4.1 van RFC 7518, welke aangeeft dat wanneer deze key gebruikt wordt om een JWE mee te maken deze JWE ook gebruik moet maken van A128KW voor alg. Andere waardes uit deze RFC die gebruikt MOGEN worden:

• A192KW
• A256KW
• dir

Na het produceren van bovenstaand Authorization Response versleutelt de App hem naar de ephemeral verifier encryption public key uit het Request Object, door het op te nemen als payload in een JWE als in § 6.3 van OpenID4VP, en stuurt het op naar de response_uri uit het Request Object, als volgt:

POST /response_uri HTTP/1.1
Content-Type: application/x-www-form-urlencoded

response=eyJra...9t2LQ

De Verifier MOET de Verifiable Presentation in de Authorization Response valideren als in § 6.5 van OpenID4VP en de "Verifiable Presentation" sectie hierboven.

De Verifier genereert met een CSPRNG een willekeurige alfanumerieke access-token die minimaal 32 karakters MOET zijn, en plaatst deze in een URI van de volgende vorm:

bk-connect://organization-discovery-url/?access-token=9YryEzKheqpx5iS2JsDNRHoydCBIsAKV&access-token-type=OpenID4VP

De Verifier antwoordt op de HTTP POST uit stap 10 met bovenstaande URI als volgt:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
  "redirect_uri": "bk-connect://organization-discovery-url/?access-token=9YryEzKheqpx5iS2JsDNRHoydCBIsAKV&access-token-type=OpenID4VP"
}

Als het valideren van de Authorization Response faalt MOET de Verifier in plaats van bovenstaande antwoorden als in § 6.4 van OpenID4VP.

De App en de Credential Issuer voeren het CreateSession protocol uit. De App MOET hierbij voor de certificate_type parameter de waarde certificate_type_self_signed gebruiken. Dit protocol resulteert in een session_token en een AES key voor later gebruik.

De App navigeert naar https://credential-issuer.example.com/register_app?session_token=..., waarbij het session_token uit de vorige stap wordt ingevuld.

(NB: in andere protocollen in deze standaard wordt het session_token uit het CreateSession protocol verstuurd in de Authorization HTTP header van een POST request. Dat is in dit geval echter niet mogelijk. Daarom wordt het session_token in dit geval middels een URL parameter in de URL van de issuer meegegeven.)

De eindgebruiker wordt geïndentificeerd middels DigiD want resulteert in diens BSN.

De Credential Issuer genereert met een CSPRNG een willekeurige alfanumerieke registration_token die minimaal 22 karakters MOET zijn (zodat hij minimaal 128 bit entropie heeft).

De Credential Issuer maakt een JSON object met daarin de volgende velden:

• sub: MOET de vaste waarde registration_token hebben.
• iss: de URL van de Credential Issuer (dat wil zeggen, de URL waar de App naartoe navigeert in stap 3, zonder register_app?session_token=...).
• registration_token: het registration_token uit stap 8.

Voorbeeld:

{
  "sub": "registration_token",
  "iss": "https://credential-issuer.example.com/",
  "registration_token": "LarRGSbmUPYtRYO6BQ4yn8"
}

Vervolgens versleutelt de Credential Issuer dit object met de session AES key in de vorm van een JWE (zie de Cryptografie sectie hierboven).

De Credential Issuer roept de Universal Link van de App aan, bijvoorbeeld door de Universal Link te plaatsen in een link op zijn website die de eindgebruiker moet gebruiken, of door een HTTP redirect naar de Universal Link. De Credential Issuer levert de volgende parameters URL-encoded mee in de Universal Link:

• registration_token: het registration token JWE uit de vorige stap.

De app ontvangt de Universal Link en parseert daaruit de registration_token.

Voorbeeld:

https://app.vorijk.nl/ul/issuance?registration_token=eyBwMry...

NB: de reden voor deze tussenstap waarin een registration_token wordt gegeven aan de app, in plaats van rechtstreeks het Verifiable Credential, is om ervoor te zorgen dat het Verifiable Credential in een latere stap rechtstreeks door de App bij de Credential Issuer kan worden opgehaald, in plaats van dat het Verifiable Credential in deze stap ook nog eens door de browser heen zou gaan voordat hij bij de App terecht komt. Bovendien zou het encoderen van het Verifiable Credential in de Universal Link deze dermate groot kunnen maken dat hij door het mobiele besturingssysteem wordt afgekapt.

De App ontsleutelt de JWE met de session AES key, en valideert dat:

1. dit resulteert in een JSON object, en
2. dat dit JSON object de velden uit Stap 11 bevat, met iss en sub de waardes zoals daar gespecificeerd.

De App maakt een JSON object met daarin de volgende velden:

• sub: MOET de vaste waarde registration_token hebben.
• iss: MOET de vaste waarde bk-connect://app/ hebben.
• registration_token: het registration_token uit stap 8.

Voorbeeld:

{
  "sub": "registration_token",
  "iss": "bk-connect://app/",
  "registration_token": "LarRGSbmUPYtRYO6BQ4yn8"
}

Vervolgens versleutelt de App dit object met de session AES key in de vorm van een JWE (zie de Cryptografie sectie hierboven).

De App verstuurt het versleutelde registration_token object naar de Credential Issuer, middels een HTTP POST naar /credential, met het session_token uit Stap 2 in de Authorization HTTP header.

Voorbeeld:

POST /credential HTTP/1.1
Host: credential-issuer.example.com
Authorization: tFNqe50B2nRSwo59ghKd6O

eyNaIioBb2_Jhb...x5Nz-g

NB: de reden dat de gebruiker het registration_token eerst moet ontsleutelen in Stap 13 en dan opnieuw moet versleutelen in Stap 15, in plaats van dat de gebruiker de versleutelde JWE die hij ontvangt in stap 12 rechtstreeks in deze stap zou kunnen versturen, is om het onmogelijk te maken voor een aanvaller die binnenin de TLS tunnel zit, en die dus het verkeer tussen de App en Credential Issuer kan zien, om de versleutelde JWE in stap 12 op te vangen en die dan in deze stap te versturen in plaats van de echte gebruiker, om op die manier het Verifiable Credential te stelen.

De Credential Issuer ontsleutelt de JWE uit de HTTP POST body van de App met de session AES key, en valideert dat:

1. dit resulteert in een JSON object, en
2. dat dit JSON object de velden uit Stap 14 bevat, met iss en sub de waardes zoals daar gespecificeerd.

De Credential Issuer tekent met zijn private key het Verifiable Credential, in de vorm van een JWS. Hierbij plaatst hij de root app EC public key in het app_public_key veld van de Verifiable Credential JWS. Zie de Verifiable Credentials sectie hierboven voor alle velden en een voorbeeld.

De App en de Credential Issuer voeren het CreateSession protocol uit. De App MOET hierbij voor de certificate_type parameter de waarde app_manager_jwt_certificate gebruiken. Dit protocol resulteert in een session_token en een AES key voor later gebruik.

De App maakt een JSON object met daarin de volgende velden:

• sub: MOET de vaste waarde unregister_app hebben.
• iss: MOET de vaste waarde bk-connect://app/ hebben.
• registration_token: het registration_token van de App.

Voorbeeld:

{
  "sub": "unregister_app",
  "iss": "bk-connect://app/",
  "registration_token": "LarRGSbmUPYtRYO6BQ4yn8"
}

Vervolgens versleutelt de App bovenstaand object met de session AES key in de vorm van een JWE (zie de Cryptografie sectie hierboven).

De App verstuurt het JWE naar de Credential Issuer, middels een HTTP POST naar /unregister_app, waarbij het session_token uit Stap 2 wordt meegegeven in de Authorization HTTP header.

Voorbeeld:

POST /unregister_app HTTP/1.1
Host: credential-issuer.example.com
Authorization: tFNqe50B2nRSwo59ghKd6O

eyNaIioBb2_Jhb...x5Nz-g

De Credential Issuer ontsleutelt de JWE uit de HTTP POST body van de App met de session AES key, en valideert dat:

1. dit resulteert in een JSON object, en
2. dat dit JSON object de velden uit Stap 3 bevat, met iss en sub de waardes zoals daar gespecificeerd.

De Credential Issuer verwijdert de registratie onder registration_token, of markeert deze als zijnde inactief, zodat een eventuele latere aanroep van het /credential HTTP endpoint in het uitgifteprotocol van voorgaande sectie die gebruik maakt van het betreffende registration_token afbreekt met een foutmelding.

De App gebruikt de OpenID4VCI en OAuth metadata discovery mechanismes door een GET uit te voeren op /.well-known/openid-credential-issuer en /.well-known/oauth-authorization-server, respectievelijk. De server(s) antwoorden met JSON structuren zoals in de Credential Issuer metadata en OAuth metadata secties hierboven. De App parseert de JSON en ontdekt op die manier de URLs van de Authorization, Token en Credential endpoints.

In het vervolg van dit document nemen we aan dat deze endpoints als volgt zijn:

• https://issuer.example.com/authorize
• https://issuer.example.com/token
• https://issuer.example.com/credential

De App genereert een PKCE verifier (genaamd code_verifier in onderstaande HTTP berichten) door 32 willekeurige bytes te genereren met een CSPRNG en deze te Base64url-encoderen, resulterend in een PKCE verifier van 43 karakters. De App genereert vervolgens de bijbehorende PKCE challenge middels de volgende pseudocode:

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

Zie ook § 4.1 en 4.2 van RFC 7636.

De App navigeert in de browser naar het Authorization endpoint van de Credential Issuer, met URL-encoded in de URL het Authorization Request als in § 5 van OpenID4VCI en § 4.1.1 van OAuth, met de volgende parameters:

• response_type: MOET de waarde code hebben (refererend naar de authorization code grant type van § 4.1 van OAuth).
• client_id: een identifier van de App die een vaste waarde MOET hebben over alle App instanties, bijvoorbeeld nl.vorijk.app.
• code_challenge: de PKCE challenge gegenereerd zoals hierboven.
• code_challenge_method: MOET de waarde S256 hebben (per § 4.2 van de PKCE RFC).
• scope: MOET de waarde nl.vorijk.oauth_scope.blauwe_knop.vc hebben, welke refereert naar de corresponderende scope uit de Credential Issuer Metadata.
• redirect_uri: dit MOET een Universal Link (UL) zijn die de App opent. Nadat authenticatie en identificatie van de eindgebruiker is gelukt zal de gebruiker in Stap 10 naar deze link worden geredirect door de Credential Issuer, waardoor de App opent.
• state: MAG aanwezig zijn en de waarde hiervan mag vrij bepaald worden door de App. Als state gebruikt wordt dan ontvangt de App dezelfde state ook terug in het Authorization Response, zie stap 10. De App kan deze parameter gebruiken voor het bijhouden van bepaalde state, bijvoorbeeld voor het tracken van verschillende sessies.

Voorbeeld (met newlines voor leesbaarheid):

https://issuer.example.com/authorize?
  response_type=code
  &client_id=nl.vorijk.app
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
  &scope=nl.vorijk.oauth_scope.blauwe_knop.vc
  &redirect_uri=https%3A%2F%2Fapp.vorijk.nl%2Ful%2Fissuance
  &state=xyz

De eindgebruiker wordt geïndentificeerd middels DigiD want resulteert in diens BSN.

De Credential Issuer genereert met een CSPRNG een nieuwe authorization code, die een willekeurige string gebruik makend van de URL-safe Base64 karakterset MOET zijn, van minimaal 22 karakters (zodat hij minimaal 128 bit entropie heeft).

De Credential Issuer slaat de PKCE challenge en het BSN van de gebruiker op onder het authorization code voor later gebruik.

De Credential Issuer roept de redirect_uri uit Stap 4 met daarin de Universal Link van de App aan, bijvoorbeeld door de Universal Link te plaatsen in een link op zijn website die de eindgebruiker moet gebruiken, of door een HTTP redirect naar de Universal Link. De Credential Issuer levert de volgende parameters URL-encoded mee in de Universal Link:

• code: de authorization code.
• state: alleen aanwezig als de App in het Authorization Request (stap 4) een state parameter heeft meegegeven, in dat geval met dezelfde waarde als in het Authorization Request.

De app ontvangt de Universal Link en parseert daaruit de authorization code.

Voorbeeld:

https://app.vorijk.nl/ul/issuance?code=SplxlOBeZQQYbYS6WxSbIA&state=xyz

De App genereert een nieuw ephemeral EC keypair, en produceert daarmee een DPoP Proof of Possession per § 4.2 van RFC 9449, welke een JWS is als volgt:

{
  "typ": "dpop+jwt",
  "alg": "ES256",
  "jwk": {
    "kty": "EC",
    "x": "l8tFrhx-34tV3hRICRDY9zCkDlpBhF42UQUfWVAWBFs",
    "y": "9VE4jf_Ok_o64zbTTlcuNJajHmt6v9TDVrU0CdvGRDA",
    "crv": "P-256"
  }
}
.
{
  "jti": "-BwC3ESc6acc2lTc",
  "htm": "POST",
  "htu": "https://issuer.example.com/token",
  "iat": 1562262616
}

In deze JWS zijn de velden als volgt:

• jwk: de zojuist gegenereerde public key in JWK formaat (RFC 7517);
• jti: De Base64url-encoding van minimaal 12 bytes aan willekeurige data gegenereerd met een CSPRNG;
• htm: de HTTP methode waarbij deze DPoP in de volgende stap gebruikt wordt;
• htu: de URL waarbij deze DPoP in de volgende stap gebruikt wordt;
• iat: de Unix timestamp van het moment van creatie van deze JWS.

De App doet een Token Request als in § 6 van OpenID4VCI en § 4.1.3 van OAuth bij de Credential Issuer, gebruik makend van de authorization code die hij eerder heeft ontvangen. De App stuurt hierbij ook bovenstaand DPoP Proof of Possession mee, per § 4.1 van RFC 9449.

De App verstuurt het Token Request URL-encoded in de HTTP POST body, met de volgende parameters:

• grant_type: MOET de waarde authorization_code hebben.
• client_id en redirect_uri: MOETEN dezelfde waardes als in het Authorization Request hebben.
• code: de authorization code ontvangen in stap 10.
• code_verifier: de PKCE verifier gegenereerd in stap 3.

Voorbeeld (met newlines voor leesbaarheid):

POST /token HTTP/1.1
Host: issuer.example.com
Content-Type: application/x-www-form-urlencoded
DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6Ik
 VDIiwieCI6Imw4dEZyaHgtMzR0VjNoUklDUkRZOXpDa0RscEJoRjQyVVFVZldWQVdCR
 nMiLCJ5IjoiOVZFNGpmX09rX282NHpiVFRsY3VOSmFqSG10NnY5VERWclUwQ2R2R1JE
 QSIsImNydiI6IlAtMjU2In19.eyJqdGkiOiItQndDM0VTYzZhY2MybFRjIiwiaHRtIj
 oiUE9TVCIsImh0dSI6Imh0dHBzOi8vc2VydmVyLmV4YW1wbGUuY29tL3Rva2VuIiwia
 WF0IjoxNTYyMjYyNjE2fQ.2-GxA6T8lP4vfrg8v-FdWP0A0zdrj8igiMLvqRMUvwnQg
 4PtFLbdLXiOSsX0x7NVY-FNyJK70nfbV37xRZT3Lg

grant_type=authorization_code
&client_id=nl.vorijk.app
&redirect_uri=https%3A%2F%2Fapp.vorijk.nl%2Ful%2Fissuance
&code=SplxlOBeZQQYbYS6WxSbIA
&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

De Credential Issuer haalt middels de authorization code de PKCE challenge en het BSN van de gebruiker op.

De Credential Issuer verifieert de PKCE verifier per § 4.6 van RFC 7636, door vast te stellen dat het volgende geldt:

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

Als deze gelijkheid niet geldt, dan MOET de Credential Issuer afbreken met de foutmelding invalid_grant als per § 5.2 van OAuth.

De Credential Issuer verifieert de DPoP Proof of Possession uit de DPoP HTTP header middels de instructies in § 4.3 van RFC 9449.

Als de DPoP JWS niet geldig is, dan MOET de Credential Issuer afbreken met de foutmelding invalid_dpop_proof als per § 5.2 van OAuth.

Als de DPoP JWS wel geldig is, dan parseert de Credential Issuer de DPoP public key in de DPoP JWS voor later gebruik.

De Credential Issuer genereert met een CSPRNG een nieuw access_token en c_nonce, die beiden willekeurige strings gebruik makend van de URL-safe Base64 karakterset MOETEN zijn, van minimaal 22 karakters (zodat ze minimaal 128 bit entropie hebben).

De Credential Issuer slaat het BSN van de gebruiker, de c_nonce en de DPoP public key op onder het access_token voor later gebruik.

De Credential Issuer antwoordt op het HTTP POST request van de App uit stap 12 met een JSON object met daarin de volgende parameters:

• access_token: het access token gegenereerd in de vorige stap, die toegang geeft tot het Credential Endpoint (zie Stap 25).
• c_nonce: de nonce gegenereerd in de vorige stap.
• token_type: MOET de waarde DPoP hebben per § 5 van RFC 9449, wat aangeeft aan de App dat DPoP gebruikt MOET worden bij het gebruik van het access token (dus bij het opvragen van het Verifiable Credential).
• expires_in: MAG aanwezig zijn en MOET in dat geval in seconden aangeven hoe lang het access token geldig is.

Voorbeeld:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
  "access_token": "JhbGciOiJSUzI1NiIsInR5",
  "c_nonce": "LarRGSbmUPYtRYO6BQ4yn8",
  "token_type": "DPoP",
  "expires_in": 60,
}

Als er niet al eerder een hardware-bound ECDSA keypair voor gebruik in het Verifiable Credential was aangemaakt doet de app dit nu.

De App genereert een Proof of Possession van de public key gegenereerd in de vorige stap als per § 7.2.1.1 van OpenID4VCI, in de vorm van een JWS met daarin de volgende velden:

• JWS header:
  • typ: MOET de waarde openid4vci-proof+jwt zijn.
  • alg: MOET de waarde ES256 zijn.
  • jwk: de ECDSA public key in JWK formaat (RFC 7517).
• JWS body:
  • aud: MOET de Credential Issuer Identifier zijn, dat wil zeggen de URL die /.well-known/openid-credential-issuer host.
  • iat: Unix timestamp van het moment van creatie van deze JWS.
  • nonce: MOET de waarde van de c_nonce hebben die de App ontving in Stap 20.

Voorbeeld:

{
  "typ": "openid4vci-proof+jwt",
  "alg": "ES256",
  "jwk": {
    "kty": "EC",
    "crv": "P-256",
    "x": "nUWAoAv3XZith8E7i19OdaxOLYFOwM-Z2EuM02TirT4",
    "y": "HskHU8BjUi1U9Xqi7Swmj8gwAK_0xkcDjEW_71SosEY"
  }
}
.
{
  "aud": "https://issuer.example.com",
  "iat": 1701960444,
  "nonce": "LarRGSbmUPYtRYO6BQ4yn8"
}

De App genereert een nieuw ephemeral EC keypair voor encryptie. Deze wordt later door de Credential Issuer gebruikt in Stap 34 om het Verifiable Credential te versleutelen voordat hij naar de App verstuurd wordt.

De App genereert een nieuw DPoP JWS zoals in stap 11, middels hetzelfde EC keypair, met een vers willekeurig jti veld, en dit keer inclusief een ath veld in de JWS body, met als waarde de Base64url-encoding van de SHA256 hash van het access_token, dus schematisch BASE64URL(SHA256(access_token)).

Voorbeeld:

{
  "typ": "dpop+jwt",
  "alg": "ES256",
  "jwk": {
    "kty": "EC",
    "x":" l8tFrhx-34tV3hRICRDY9zCkDlpBhF42UQUfWVAWBFs",
    "y": "9VE4jf_Ok_o64zbTTlcuNJajHmt6v9TDVrU0CdvGRDA",
    "crv": "P-256"
  }
}
.
{
  "jti": "e1j3V_bKic8-LAEB",
  "htm": "POST",
  "htu": "https://issuer.example.org/credential",
  "iat": 1562262618,
  "ath": "LnCUSTkzMbG3p5Bw35U4EAOl-pXwcgOdhXxgK6CFYY4"
}

De App stuurt een Credential Request naar het Credential endpoint van de Credential Issuer als in § 7 van OpenID4VCI, middels een HTTP POST met de volgende HTTP headers:

• Authorization: het access token met DPoP als authentication scheme.
• DPoP: de DPoP JWS uit de vorige stap.

In de HTTP body verstuurt de App JSON-encoded een object met de volgende parameters:

• proof: een object met daarin:
  • proof_type: MOET de waarde jwt hebben.
  • jwt: de JWS uit stap 22.
• credential_response_encryption: een object dat aangeeft hoe de Credential Issuer het Verifiable Credential moet versleutelen voordat het naar de App gestuurd wordt, middels de volgende velden:
  • jwk: de public key gegenereerd in Stap 23.
  • alg: het asymmetrische encryptie-algoritme die de app verwacht. MOET de waarde ECDH-ES hebben.
  • enc: het symmetrische encryptie-algoritme die de app verwacht. MOET de waarde A128GCM, A192GCM, of A256GCM hebben.

Voorbeeld (newlines en whitespace enkel voor leesbaarheid):

POST /credential HTTP/1.1
Host: issuer.example.com
Content-Type: application/json
Authorization: DPoP JhbGciOiJSUzI1NiIsInR5
DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6Ik
 VDIiwieCI6Imw4dEZyaHgtMzR0VjNoUklDUkRZOXpDa0RscEJoRjQyVVFVZldWQVdCR
 nMiLCJ5IjoiOVZFNGpmX09rX282NHpiVFRsY3VOSmFqSG10NnY5VERWclUwQ2R2R1JE
 QSIsImNydiI6IlAtMjU2In19.eyJqdGkiOiJlMWozVl9iS2ljOC1MQUVCIiwiaHRtIj
 oiR0VUIiwiaHR1IjoiaHR0cHM6Ly9yZXNvdXJjZS5leGFtcGxlLm9yZy9wcm90ZWN0Z
 WRyZXNvdXJjZSIsImlhdCI6MTU2MjI2MjYxOCwiYXRoIjoiZlVIeU8ycjJaM0RaNTNF
 c05yV0JiMHhXWG9hTnk1OUlpS0NBcWtzbVFFbyJ9.2oW9RP35yRqzhrtNP86L-Ey71E
 OptxRimPPToA1plemAgR6pxHF8y6-yqyVnmcw6Fy1dqd-jfxSYoMxhAJpLjA

{
  "proof": {
    "proof_type": "jwt",
    "jwt":
      "eyJ0eXAiOiJvcGVuaWQ0dmNpLXByb29mK2p3dCIsImFsZyI6IkVTMjU2IiwiandrI
      jp7Imt0eSI6IkVDIiwiY3J2IjoiUC0yNTYiLCJ4IjoiblVXQW9BdjNYWml0aDhFN2k
      xOU9kYXhPTFlGT3dNLVoyRXVNMDJUaXJUNCIsInkiOiJIc2tIVThCalVpMVU5WHFpN
      1N3bWo4Z3dBS18weGtjRGpFV183MVNvc0VZIn19.eyJhdWQiOiJodHRwczovL2NyZW
      RlbnRpYWwtaXNzdWVyLmV4YW1wbGUuY29tIiwiaWF0IjoxNzAxOTYwNDQ0LCJub25j
      ZSI6IkxhclJHU2JtVVBZdFJZTzZCUTR5bjgifQ.-a3EDsxClUB4O3LeDD5DVGEnNMT
      01FCQW4P6-2-BNBqc_Zxf0Qw4CWayLEpqkAomlkLb9zioZoipdP-jvh1WlA"
  },
  "credential_response_encryption": {
    "jwk": {
      "kty": "EC",
      "crv": "P-256",
      "x": "gUOuh9dfi-44HT-2YL5HdEZ9opP_ItHrpp28JtQyaOY",
      "y": "0UOvHfidVyKFN4gDz9bIstU0o0qWCaZrRaVhplgkm58"
    },
    "alg": "ECDH-ES",
    "enc": "A128GCM"
  }
}

De Credential Issuer haalt middels het access token het BSN van de gebruiker, de c_nonce en de DPoP public key op.

De Credential Issuer verifieert de DPoP JWS uit de DPoP HTTP header net als in stap 16, dit keer met de volgende extra checks:

• de DPoP JWS MOET een ath veld hebben met daarin de Base64url-encoding van de SHA256 hash van het access token;
• de public key in het JWK veld MOET gelijk zijn aan degene die de Credential Issuer aantrof in stap 16.

De Credential Issuer verifieert de Proof of Possession in het jwt veld in het proof object van de Credential Response als volgt.

1. Parseer de JWS header (nog zonder de JWS geverifieerd te hebben).
2. Controleer dat het typ veld in de JWS header de waarde openid4vci-proof+jwt bevat.
3. Controleer dat het alg veld in de JWS header de waarde ES256 bevat.
4. Controleer dat het jwk veld in de JWS header een object bevat die een P-256 public key is geëncodeerd als JWK, en dat dit object niet een d veld (een private key) in zich heeft.
5. Verifieer de JWS tegen de public key uit bovenstaande stap.
6. Controleer dat het aud veld in de JWS body de Credential Issuer Identifier bevat (de URL die /.well-known/openid-credential-issuer host).
7. Controleer dat de JWS volgens het iat veld in de JWS body niet ouder is dan een bepaalde grens, bijvoorbeeld 60 seconden.
8. Controleer dat de nonce in de JWS body gelijk is aan de c_nonce die in Stap 20 aan de App is verstrekt.

Middels het BSN worden de gegevens van de eindgebruiker die geïssued moeten worden als attributen in het Verifiable Credential opgehaald uit de BRP.

De Credential Issuer tekent met zijn private key het Verifiable Credential, in de vorm van een JWS. Hierbij plaatst hij de public key in het jwk veld van het Proof of Possession (zie Stap 29) in het cnf veld van de Verifiable Credential JWS. Zie de Verifiable Credentials sectie hierboven voor alle velden en een voorbeeld.

De Credential Issuer maakt het Credential Response, een JSON object met daarin enkel een credential veld met als waarde de JWS uit de vorige stap:

{
  "credential": "eyBRa..."
}

De Credential Issuer versleutelt dit object in de vorm van een JWE naar de public key in het jwk veld in het credential_response_encryption object in het Credential Request uit Stap 25.

De Credential Issuer verstuurt bovenstaand JWE naar de App.

De App controleert dat het Credential Response versleuteld in de vorm van een JWE is, en breekt af zoniet. Hij ontsleutelt de JWE met de private key gegenereerd in Stap 23, parseert de inhoud van de JWE als JSON object, en vindt daarin het Verifiable Credential in het credential veld.

De App verifieert het Verifiable Credential tegen de public key van de Credential Issuer, eventueel gebruik makend van het kid veld in de JWS header om de juiste public key te identificeren.