Interfaces Autorisatie Server GTK

Metadata Interface

Metadata

De metadata van de Autorisatie Server kan, conform RFC 8414, worden opgehaald op een well-known URL die kan worden geconstrueerd m.b.v. de  <iss> claim uit het token (zie ook section-3.1 van RFC8414). De Authorization Server Metadata Response bevat de volgende attributen. Dit betekent dat bij een iss die gelijk is aan: https://FQDN/some-path-extension, de metadata kan worden verkregen bij: https://FQDN/.well-known/oauth-authorization-server/some-path-extension.

De metadata omvat de volgende attributen:

• issuer;

• token_endpoint;

• jwks_uri;

• response_types_supported;

• signed_metadata.

De response die wordt geretourneerd bevat daarnaast de volgende headers:

Cache-Control: must-revalidate, max-age=<max-age-metadata>
Pragma: no-cache

Een client mag verkregen metadata conform de Cache-Control header directives, zoals beschreven in RFC 7234, cachen.

De waarde van max-age-metadata is configureerbaar in de autorisatie server. Initiële waarde is 14400 seconden (4 uur).

Toelichting verkrijgen JWKS

Wanneer een uitgegeven token/assertion een iss attribuut bevat met waarde:

• “https://zim.prf001.lsp.aorta-zorg.nl/asgtk/jwt”

Dan kan de metadata op de volgende wijze worden opgehaald:

• GET https://zim.prf001.lsp.aorta-zorg.nl/.well-known/oauth-authorization-server/asgtk/jwt

De metadata bevat dan ondermeer een attribuut jwks_uri. Dit attribuut kan bijvoorbeeld de volgende waarde hebben:

• “https://zim.prf001.lsp.aorta-zorg.nl/asgtk/jwks.json”

De JWKS kan dan op de volgende wijze worden opgehaald:

• GET https://zim.prf001.lsp.aorta-zorg.nl/asgtk/jwks.json

Een server die de signature van een token/assertion wil controleren hoeft dus vooraf geen informatie te hebben over de publieke sleutel, of over een uri waarop een sleutel kan worden verkregen. De benodigde informatie komt mee via de iss claim van het betreffende token/assertion.

Voor servers die tokens/assertions willen controleren is het wel zaak om een registratie te hebben van iss URL’s die je vertrouwt, en van wie je tokens/assertions accepteert.

JWKS

De public key waarmee de digitale handtekening kan worden gecontroleerd wordt als een JWK beschikbaar gesteld. De URL waarop de JWK Set kan worden opgevraagd (jwks_uri) maakt deel uit van de AS metadata response. Iedere JSON Web Key (JWK) in de set, die beschikbaar wordt gesteld op de jwks_uri, bevat een kid parameter. De juiste JWK in de JWK Set wordt gevonden o.b.v. de waarde van het kid attribuut in de header van de ontvangen JWT.

De response die wordt geretourneerd na een HTTP GET op de jwks_uri bevat naast de JWK Set de volgende headers:

Cache-Control: must-revalidate, max-age=<max-age-jwks>
Pragma: no-cache

Een client mag verkregen JWK's conform de Cache-Control header directives, zoals beschreven in RFC 7234, cachen.

De waarde van max-age-jwks is configureerbaar in de autorisatie server. Initiële waarde is 14400 seconden (4 uur).

De JWK bevat de volgende attributen, waar de definitie van de attributen kan worden gevonden in RFC 7517 en RFC 7518:

• "kty":"EC"

• "alg":"ES512"

• "use":"sig"

• "kid":"<the identifier of the key-pair used to sign this JWT>"

• "x5c":"<de van toepassing zijnde keten van PKIX certificaten>"

• "crv":"P-521"

• "x":"<the x coordinate for the Elliptic Curve point>"

• "y":"<the y coordinate for the Elliptic Curve point>"

TWIIN Assertion Interface

Inhoud en formaat van een issueAssertionsRequest

Middels deze interface kunnen een Twiin client_assertion en een Twiin assertion worden verkregen op basis van een AORTA access_token.

Een issueAssertionsRequest wordt op de volgende wijze verzonden:

POST [base endpointadres]/issueAssertionsRequest/v1

Bij het verzenden van een issueAssertionsRequest dienen de volgende HTTP headers te worden meegezonden:

AORTA-ID: initialRequestID=<UUID conform RFC4122>; requestID=<UUID conform RFC4122>

Het initialRequestID attribuut bevat het ID van het allereerste request in de hele keten en dient te worden opgenomen in de logbestanden van alle partijen in de keten, zodat bij foutopsporing de verschillende logbestanden aan elkaar kunnen worden gerelateerd.

Het requestID is voor iedere request message uniek. In requests wordt deze gegenereerd door de client. Ook het requestID dient te worden opgenomen in de verschillende logbestanden, zodat altijd duidelijk is op welk bericht een log entry van toepassing is.

Content-Type: application/json; charset=utf-8

Het technische formaat van de HTTP body van een issueAssertionsRequest is:

{
  "sourceTokenType": "",
  "sourceToken": "",
  "clientId": "",
  "audience": ""
}

Input parameters:

Inhoud en formaat van een issueAssertionsResponse

Bij het verzenden van een issueAssertionsResponse dienen de volgende HTTP headers te worden meegezonden:

Content-Type: application/json; charset=utf-8

Het technische formaat van de HTTP body van een issueAssertionsResponse is:

{
  "clientAssertion": "",
  "assertion": "",
  "scope": ""
}

Output parameters:

HTTP statuscodes

HTTP statuscodes die kunnen worden geretourneerd zijn opgenomen in onderstaande tabel.

Omdat bepaalde Confluence macro’s nog niet worden ondersteund in de publicatie omgeving, bevat de tabel, in de publicatieomgeving, ook informatie over de wijze waarop de betreffende interface wordt geïmplementeerd in de server component. De statuscodes die kunnen worden geretourneerd zijn opgenomen in de kolom “Uitkomst”. De overige informatie mag worden genegeerd.

TWIIN Token Interface

De TWIIN Token Interface is gespecificeerd in het TWIIN afsprakenstelsel:

• https://twiin-afsprakenstelsel.scrollhelp.site/ta12/10-2-5-tta-fhir-authentication-authorization#id-10.2.5%7CTTAFHIR-Authentication&Authorization-Accesstokenrequest

Deze interface is gebaseerd op het Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants, en specifiek hierbinnen op het JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants.

Een tokenRequest wordt op de volgende wijze verzonden:

POST [base endpointadres]/token/v1