Skip to main content
Skip table of contents

Interfaces Autorisatie Server ZA

Metadata Interface

Feature

getMetadataZA

Type

Service

Versie

1.0.0

Groep

Autorisatie

Gepubliceerd

Delta

Initiële versie van feature.

Use case

-

Feature

Versie

Dependency

Aanbieder

Afnemer

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).

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":"RSA"

  • "alg":"RS256"

  • "use":"sig"

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

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

  • "n":"<the modulus value for the RSA public key>"

  • "e":"<the exponent value for the RSA public key>"

AORTA Token Interface

AORTA Token Exchange

Feature

AORTA Token Exchange

Type

Service

Versie

1.5.2

Groep

Autorisatie

Gepubliceerd

Delta

Toegevoegd dat uitgaande requests en ontvangen responses ook moeten worden gelogd in de componentenlog.

Use case

AOF.UC.ASZA.100.v4

De AORTA Token Exchange Interface is gebaseerd op OAuth token exchange.

Ondersteunde versies (ver attribuut) van het AORTA access_token zijn:

  • 2.0

  • 3.2

  • 4.0

Op deze interface wordt een AORTA access_token geretourneerd conform de hoogste versie die de uiteindelijke bestemming van een interactie ondersteund.

Een tokenExchangeRequest wordt op de volgende wijze verzonden:

POST [base endpointadres]/tokenx/v1

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

Feature

AORTA-ID HTTP Header

Type

Subfeature

Versie

1.0.0

Groep

HTTP Headers

Gepubliceerd

Delta

Initiële versie van feature.

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.

Een tokenExchangeRequest bevat de volgende attributen:

Parameter

Cardinaliteit

Toelichting

grant_type

1..1

Vaste waarde "urn:ietf:params:oauth:grant-type:token-exchange"

client_id

0..1

Het appID van de client die een FHIR-interactie wil initiëren. Hoeft slechts te worden meegezonden, wanneer het niet is opgenomen in het actor_token. Vooralsnog daarom slechts van toepassing voor interacties vanuit een GBP.

Formaat: "urn:oid:2.16.840.1.113883.2.4.6.6.<applicatie-id>".

audience

0..1

Bij geadresseerde interacties tussen GBx-applicaties:

Waarde is "<appID van GBZ-applicatie>" OF “<URA van zorgaanbieder> <appID van GBZ-applicatie>“.

NB. indien een URA en een appID worden meegegeven, en het appID behoort tot een GBZ-applicatie in AORTA (en dus niet tot Resource Broker GTK), dan zal de Autorisatie Server slechts een AORTA access_token uitgeven voor dit specifieke appID.

Wanneer de client een FHIR-update of een FHIR-read interactie wil uitvoeren, dan is het juiste appID opgenomen in de base-URL van de betreffende resource instance, zoals eerder ontvangen. Instance-level interacties, zoals een read en een update dienen altijd te worden gericht aan één GBZ-applicatie, en nooit aan een URA.

Wanneer de client een ander soortige FHIR-interactie wil uitvoeren, dan zijn er een aantal mogelijkheden:

  1. De client bepaalt zelf, m.b.v. de systeemrollen en conformances, zoals gevonden in ZORG-AB, en m.b.v. de transformatie server metadata, welk(e) GBZ-applicatie(s), eventueel na translatie, de betreffende interactie kan/kunnen ontvangen.

  2. De client vraagt de Adressering Server, welk(e) GBZ-applicatie(s), eventueel na translatie, de betreffende interactie kan/kunnen ontvangen.

Bij geadresseerde interacties tussen een GBx-applicatie en een GTK:

Waarde is “<URA van zorgaanbieder> <appID van Resource Broker GTK>”.

Bij interacties tussen een GBx-applicatie en een Resource Broker component:

Waarde is "<role van betreffende Resource Broker component>".

Bij geadresseerde FHIR $get-aorta-data operation:

Waarde is "<URA van het GBZ>" of “<appID van GBZ-applicatie>”.

Bij ongeadresseerde/gespreide FHIR $get-aorta-data operation:

Niet aanwezig.

Formaat van een appID: "urn:oid:2.16.840.1.113883.2.4.6.6.<applicatie-id>".

Formaat van een URA: "urn:oid:2.16.528.1.1007.3.3.<URA>".

Formaat van een role: "urn:oid:2.16.840.1.113883.2.4.3.111.8.<role-id>"

requested_token_type 

1..1

Vaste waarde "urn:ietf:params:oauth:token-type:jwt".

subject_token

1..1

A security token that represents the identity of the party on behalf of whom the request is being made. Typically, the subject of this token will be the subject of the security token issued in response to the request.

Wanneer geen actor_token aanwezig is, dan is het subject_token een AORTA SAML transactietoken, een SAML PKIo Authenticatietoken, een SAML DigiD token.

Wanneer wel een actor_token aanwezig is, dan is het subject token een AORTA SAML mandaattoken.

subject_token_type  

1..1

Type aanduiding van het subject_token. Vaste waarde "urn:ietf:params:oauth:token-type:saml2". Geeft aan dat het token een base64url-encoded SAML 2.0 Assertion is.

actor_token

0..1

A security token that represents the identity of the acting party. Typically, this will be the party that is authorized to use the requested security token and act on behalf of the subject.

Een actor_token is slechts aanwezig wanneer de acting party een andere is dan het subject.

Een actor_token is altijd een AORTA SAML transactietoken. Het subject_token is in dat geval dan een AORTA SAML mandaattoken.

actor_token_type

0..1

Type aanduiding van het actor_token. Vaste waarde "urn:ietf:params:oauth:token-type:saml2". Geeft aan dat het token een base64url-encoded SAML 2.0 Assertion is.

registration_token

0..1

Het registration_token is een AORTA SAML inschrijftoken.

registration_token_type

0..1

Type aanduiding van het registration_token. Vaste waarde "urn:ietf:params:oauth:token-type:saml2". Geeft aan dat het token een base64url-encoded SAML 2.0 Assertion is.

consent_token

0..1

Het consent_token is een AORTA SAML consent_token.

Dit attribuut zal slechts worden gevuld wanneer een AORTA access_token wordt gevraagd voor een pull interactie die wordt uitgevoerd n.a.v. een ontvangen notificatie (notified-pull).

De volgende situaties zijn mogelijk:

  1. De ontvangen notificatie komt van een AORTA deelnemer, en bevat een AORTA consent_token;

  2. De ontvangen notification komt van een extern GTK, en bevat een opaque authorization_base;

  3. De ontvangen notification komt van een extern GTK, en bevat géén authorization_base.

Let op: in de laatste situatie zal dus ook geen consent_token attribuut worden meegezonden in het token exchange request.

consent_token_type

0..1

Type aanduiding van het consent_token. Vaste waarde "urn:ietf:params:oauth:token-type:saml2". Geeft aan dat het token een base64url-encoded SAML 2.0 Assertion is.

Dit attribuut mag slechts worden gevuld met bovenstaande vaste waarde, wanneer het consent_token attribuut is gevuld.

Let op: een authorization_base en een consent_token zijn feitelijk opaque voor een resource client. Een resource client mag geen afhankelijkheid nemen op de inhoud ervan, en zal dus ook het consent_token_type niet kennen.

Om deze reden zal dit attribuut worden uitgefaseerd. Het mag nu nog worden gevuld. Maar een resource client mag het ook weglaten.

scope

1..1

Een string met daarin de gevraagde scope van autorisatie, die bestaat uit de volgende opeenvolgende delen, van elkaar gescheiden door een "~":

  • Een door spaties van elkaar gescheiden set van AORTA interaction-id's, bijvoorbeeld "search:eAfspraak-Appointment:2", "operation:$get-aorta-data:1" of "GQZG_IN000001NL“;

  • De contextCode, waarbinnen de interacties plaatsvinden, bijvoorbeeld "aorta.contextcode.BGZ" - niet aanwezig wanneer een v3-pushbericht wordt verzonden;

  • Een aanduiding van de situatie waarin de interactie plaatsvindt, "normaal" of "nood". Vooralsnog is deze parameter gevuld met vaste waarde "normaal".

Voorbeelden scope:

  • Opvragen van specifieke resources bij een GBZ-applicatie: "search:eAfspraak-Appointment:2 search:zib-LivingSituation:2~aorta.contextcode.BGZ~normaal".

  • Verzenden van een v3-pushbericht via Resource Broker v3-in (dus t.b.v. een v3-client): “PVMV_IN932000NL03~~normaal“.

  • Verzenden van een FHIR pushbericht via Resource Broker ZA-in (dus t.b.v. een FHIR-client): “transaction:mp-MedicationPrescription-Bundle:1~aorta.contextcode.MEDPRESC~normaal“.

  • (Her)aanmelden van een entry bij VWI/ACT: “update:aorta-DataReference:1~VWIMGT~normaal“.

  • Opvragen van entries bij VWI/ACT door patiënt (GBP): “search:aorta-DataReference:1~PATVWI~normaal“.

  • Registreren van een nieuwe abonnement: “create:aorta-subscription:1~aorta.contextcode.MEDGEGTOT~normaal“.

  • Wijzigen van een abonnement: “update:aorta-subscription:1~aorta.contextcode.MEDGEGTOT~normaal“.

  • Beëindigen van een abonnement: “delete:aorta-subscription:1~aorta.contextcode.MEDGEGTOT~normaal“.

  • Opvragen van abonnementen: “search:aorta-subscription:1~aorta.contextcode.OPVABR~normaal“.

Mogelijke combinaties van subject_token, actor_token, registration_token en consent_token zijn:

Initiator

subject_token

actor_token

registration_token

consent_token

GBZ

AORTA SAML transactie_token, gesigned met een UZI-servercertificaat

-

-

-

AORTA SAML transactie_token, gesigned met een UZI-pas (zorgverlenerspas)

-

-

Slechts aanwezig wanneer de initiator een "notified-pull" uitvoert (dus een pull n.a.v. een notificatie).

AORTA SAML mandaat_token, gesigned met een UZI-pas (zorgverlenerpas)

AORTA SAML transactie_token, gesigned met een UZI-pas (zorgverlenerspas of medewerkerpas op naam)

-

Slechts aanwezig wanneer de initiator een "notified-pull" uitvoert (dus een pull n.a.v. een notificatie).

AORTA SAML mandaat_token, gesigned met een UZI-pas (zorgverlenerpas)

AORTA SAML transactie_token, gesigned met een UZI-servercertificaat

-

Aanwezig.

Deze combinatie van tokens is slechts mogelijk bij een pull n.a.v. een notificatie.

AORTA SAML mandaat_token, gesigned met een UZI-pas (zorgverlenerpas)

AORTA SAML transactie_token, gesigned met een UZI-servercertificaat

AORTA SAML inschrijf_token, gesigned met een UZI-pas (zorgverlenerpas)

-

GBK

SAML PKIo Authenticatietoken, gesigned met een PKIo-pas

-

-

-

GBP

SAML DigiD token

-

-

-

Voorbeeld van een tokenExchangeRequest:

POST [base]/tokenx/v1
Content-Type: application/x-www-form-urlencoded
AORTA-ID: initialRequestID=<UUID conform RFC4122>; requestID=<UUID conform RFC4122>

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange
&audience=urn%3Aoid%3A2.16.840.1.113883.2.4.6.6.352
&requested_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt
&subject_token=<base64url-encoded SAML Assertion>
&subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Asaml2
&actor_token=<base64url-encoded SAML Assertion>
&actor_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Asaml2
&registration_token=<base64url-encoded SAML Assertion>
&registration_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Asaml2
&consent_token=<base64url-encoded SAML Assertion>
&consent_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Asaml2
&scope=search%3AeAfspraak-Appointment%3A2%20search%3Azib-LivingSituation%3A2~aorta.contextcode.BGZ~normaal

Een tokenExchangeResponse bevat de volgende attributen:

Parameter

Cardinaliteit

Toelichting

access_token

1..1

Een JWT-based AORTA access_token. Er wordt één token uitgegeven met een audience element voor ieder te bevragen xIS van deze zorgaanbieder, die om kan gaan met het requested_token_type.

issued_token_type 

1..1

Type aanduiding van de representatievorm van het uitgegeven access_token. Vaste waarde "urn:ietf:params:oauth:token-type:jwt".

token_type 

1..1

Vaste waarde "Bearer".

expires_in 

1..1

Geldigheid in seconden van het uitgegeven AORTA access_token. Deze bedraagt 20 seconden.

scope 

1..1

Dezelfde string, zoals ontvangen in het token exchange response, maar met daarin slechts de onderdelen die daadwerkelijk zijn toegekend.

Wanneer een transformatie is vereist voor een interactie, dan wordt dit in de geretourneerde scope aangegeven door het interactie-id uit te breiden met "/<transformation-id>".

Voorbeelden van een geretourneerde scope:

  • Opvragen van specifieke resources bij een GBZ-applicatie: "search:eAfspraak-Appointment:2 search:zib-LivingSituation:2~aorta.contextcode.BGZ~normaal".

  • Opvragen van resource bij een GBZ-applicatie, waarvoor transformatie is vereist: "search:eAfspraak-Appointment:2/3~aorta.contextcode.AFSPR~normaal".

  • Uitvoeren van operation $get-aorta-data: "operation:$get-aorta-data:1~aorta.contextcode.BGZ~normaal".

Te hanteren error responses zijn eveneens beschreven in RFC 8693.

Voorbeeld van een tokenExchangeResponse:

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

{
    "access_token": "2YotnFZFEjr1zCsicMWpAA",
    "issued_token_type": "urn:ietf:params:oauth:token-type:jwt",
    "token_type": "Bearer",
    "expires_in": 20,
    "scope": "search:eAfspraak-Appointment:2/3~aorta.contextcode.AFSPR~normaal"
}

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.

Stap

Omschrijving

Uitkomst

1

Het systeem ontvangt een verzoek en start de verwerking.

2

Het systeem controleert of het ontvangen request voldoet aan de AORTA interface specificaties.

Ongeldig verzoek

statuscode 400 Bad Request, error=invalid_request

Het systeem genereert de vereiste foutresponse en gaat verder met de exit stap van de main flow.

3

Indien deze use case wordt doorlopen voor Feature AORTA Token Exchange, dan controleert het systeem, indien niet kan worden gegarandeerd dat dit al is gedaan door de primaire actor, de geldigheid van de meegezonden, van toepassing zijnde, tokens:

  • subject_token

    • AORTA transactietoken, zoals omschreven in de sectie "Toetsing AORTA transactietoken".

    • DigiD token, zoals omschreven in de sectie "Toetsing DigiD Authenticatietoken".

    • PKIo Authenticatietoken, zoals omschreven in de sectie "Toetsing PKIo Authenticatietoken".

    • AORTA mandaattoken), zoals omschreven in de sectie "Toetsing AORTA mandaattoken".

  • actor_token

  • registration_token (AORTA inschrijftoken), zoals omschreven in de sectie "Toetsing AORTA inschrijftoken".

  • consent_token (AORTA consent_token), zoals omschreven in de sectie "Toetsing AORTA consent_token".

Ongeldig verzoek

statuscode 400 Bad Request, error=invalid_request

Het systeem genereert de vereiste foutresponse en gaat verder met de exit stap van de main flow.

4

Indien geen scope parameter is ontvangen, maar wel een AORTA consent_token, dan bepaalt het systeem, m.b.v. Feature getInteractionContexts (SDS), voor welke FHIR interactie(s) een AORTA access_token wordt gevraagd.

NB. omdat de scope van een consent_token vooralsnog altijd betrekking heeft op één of meerdere pull interacties, gericht aan een GBx-applicatie, en die moeten worden uitgevoerd op betrouwbaarheidsniveau Midden of hoger, kan ervan worden uitgegaan dat deze scope is opgenomen in de SDS.

Géén interactie(s) gevonden

statuscode 400 Bad Request, error=invalid_request

5

Het systeem controleert, m.b.v. het APR, of de Resource Client (GBx-applicatie) beschikt over de conformances en systeemrollen, die zijn vereist voor de beoogde interactie(s), en voor de meegezonden tokens.

Client niet gekwalificeerd voor één of meerdere interactie(s)

statuscode 403 Forbidden, error=access_denied, error_description="Initiërende applicatie beschikt niet over de vereiste capabilities."

Het systeem genereert de vereiste foutresponse en gaat verder met de exit stap van de main flow.

6

Het systeem bepaalt, m.b.v. de MAP Interface, welk van de gevraagde interacties, gegeven het gehanteerde betrouwbaarheidsniveau, zijn toegestaan conform het Medisch Autorisatie Protocol.

Géén van de interacties is toegestaan

statuscode 403, error=access_denied

Het systeem genereert de vereiste foutresponse en gaat verder met de exit stap van de main flow.

7

Indien de beoogde interactie operation $get-aorta-data of een generieke v3-query betreft, die bestemd is voor de resource broker, dan genereert het systeem het vereiste AORTA access_token, en gaat verder naar de exit stap van de flow. Access_tokens mogen niet door het systeem worden opgeslagen.

8

Het systeem bepaalt, voor interacties die in de AORTA interactietabel zijn gemarkeerd als een pull-interactie, en die niet zijn gericht aan een VZVZ component, m.b.v. Feature getInteractionContexts (SDS), welke inperkende zoekparameters eventueel moeten worden opgenomen in de scope van het uit te geven AORTA access_token. Hierbij wordt rekening gehouden met of een attribuut in de SDS al dan niet als overridable is aangemerkt.

Voor interacties die zijn gemarkeerd als een push-interactie bepaalt het systeem, a.d.h.v. de AORTA interactietabel (classifier attribuut), of er inperkende attributen zijn die moeten worden opgenomen in de scope van het access_token.

NB. alle pull-interacties en bijbehorende contextcodes horen altijd opgenomen te zijn in de SDS, omdat het uitgangspunt is dat een specifieke opvraag in combinatie met een bepaalde contextcode ook moet kunnen worden getriggered middels een $get-aorta-data of generieke query met deze contextcode.

Combinatie van operation, contextcode en rolcode niet gevonden

statuscode 400 Bad Request, error=invalid_request

Classifier in interactietabel heeft andere waarde in SDS

statuscode 500

Het systeem genereert de vereiste foutresponse en gaat verder met de exit stap van de main flow.

9

Indien de destination van het request een appID of URA bevat, dan bepaalt het systeem, m.b.v. de Routing Info Interface, welke interactie(s) door de betreffende bestemming kunnen worden ontvangen.

NB. indien een URA en een appID worden meegegeven, en het appID behoort tot een GBZ-applicatie in AORTA (en dus niet tot Resource Broker GTK), dan vraagt het systeem slechts slechts Routing Info voor dit specifieke appID. Wanneer het appID behoort tot Resource Broker GTK, dan vraagt het systeem juist Routing Info voor de meegegeven URA.

Géén appID gevonden

statuscode 403, error=access_denied, error_description="Ontvangende applicatie beschikt niet over de vereiste capabilities."

Het systeem genereert de vereiste foutresponse en gaat verder met de exit stap van de main flow.

10

Indien de destination in het request een GBZ-applicatie (appID) bevat, niet zijnde Resource Broker GTK, en blijkens de scope in het request gegevens worden opgevraagd, dan toetst het systeem of de betreffende patiënt toestemming heeft gegeven voor de gevraagde scope van autorisatie, zoals beschreven in "Toelichting controle toestemming patiënt".

Géén van de interacties is toegestaan

statuscode 403, error=access_denied

Fout bij bepalen status van toestemming

statuscode 500

Het systeem genereert de vereiste foutresponse en gaat verder met de exit stap van de main flow.

11

Indien het request een interactie betreft m.b.t. een AuditEvent, en blijkens de destination van het request is bestemd voor de resource broker zelf (rb_log), dan voert het systeem de controles uit, zoals beschreven in "specifieke autorisatieregels RB-logging". Eventuele inperkingen die van toepassing zijn worden uitgedrukt in de scope van het uit te geven AORTA access_token.

Géén van de interacties is toegestaan

statuscode 403, error=access_denied

Het systeem genereert de vereiste foutresponse en gaat verder met de exit stap van de main flow.

12

Indien het request een interactie betreft die deel uitmaakt van de Actualiteitsregister Interface, en blijkens de destination van het request is bestemd voor de resource broker zelf (rb_vwi), dan voert het systeem de controles uit, zoals beschreven in "specifieke autorisatieregels ACT/VWI". Eventuele inperkingen die van toepassing zijn worden uitgedrukt in de scope van het uit te geven AORTA access_token.

Géén van de interacties is toegestaan

statuscode 403, error=access_denied

Het systeem genereert de vereiste foutresponse en gaat verder met de exit stap van de main flow.

13

Indien het request een interactie betreft m.b.t. een Subscription, en blijkens de destination van het request is bestemd voor het Abonnementenregister (rb_abr), dan voert het systeem de controles uit, zoals beschreven in "specifieke autorisatieregels Abonnementenregister". Eventuele inperkingen die van toepassing zijn worden uitgedrukt in de scope van het uit te geven AORTA access_token.

Géén van de interacties is toegestaan

statuscode 403, error=access_denied

Het systeem genereert de vereiste foutresponse en gaat verder met de exit stap van de main flow.

14

Het systeem genereert het vereiste AORTA access_token, conform de hoogste versie die wordt ondersteund door de audience. Access_tokens mogen niet door het systeem worden opgeslagen. Voor de vulling van de scope van het access_token wordt gebruik gemaakt van classificerende attributen, zoals benoemd in de AORTA interactietabel, en indien van toepassing ook van te hanteren zoekparameters die zijn verkregen uit de SDS. Zie ook de “Toelichting vulling smart-on-fhir scope en _vrb_ter_scope in het AORTA access_token”.

15

<exit>

Het systeem retourneert een response naar de primaire actor.

AORTA Token Expansion

Feature

AORTA Token Expansion

Type

Service

Versie

2.2.2

Groep

Autorisatie

Gepubliceerd

Delta

Toegevoegd dat uitgaande requests en ontvangen responses ook moeten worden gelogd in de componentenlog.

Use case

AOF.UC.ASZA.200.v3

De AORTA Token Expansion 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.

Ondersteunde versies (ver attribuut) van het AORTA access_token zijn:

  • 1.1

  • 2.0

  • 3.2

  • 4.0

Op deze interface wordt een AORTA access_token geretourneerd conform de hoogste versie die de uiteindelijke bestemming van een interactie ondersteund.

Een tokenExpansionRequest wordt op de volgende wijze verzonden:

POST [base endpointadres]/token/v2

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

Feature

AORTA-ID HTTP Header

Type

Subfeature

Versie

1.0.0

Groep

HTTP Headers

Gepubliceerd

Delta

Initiële versie van feature.

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.

Een tokenExpansionRequest bevat de volgende attributen (zie ook sectie 2.1 van RFC 7523):

Parameter

Cardinaliteit

Toelichting

grant_type

1..1

Vaste waarde "urn:ietf:params:oauth:grant-type:jwt-bearer".

assertion

1..1

Een JWT-based AORTA access_token. Dit token is enkel bedoeld voor de Resource Broker, en niet voor achterliggende GBx-servers.

scope

1..1

Het scope attribuut bestaat uit een clinical data scope conform SMART-on-FHIR 2.0, waarbij ook fine-grained constraints kunnen worden opgenomen in de vorm van search-parameters, waarmee eventuele parameters die zijn meegezonden in de $get-aorta-data operation of the hybride generieke v3-query worden doorgegeven.

Voorbeelden:

  • "patient$get-aorta-data?context=MEDGEG&destination=urn:oid:2.16.528.1.1007.3.3.<URA>"

  • "patient$get-aorta-data?context=MEDGEG&destination=urn:oid:2.16.840.1.113883.2.4.6.6.<app-id>"

  • "patient$get-aorta-data?context=MEDGEG&effective-time=ge2010-01-01&effective-time=le2011-12-31"

  • "patient$get-aorta-data?context=MEDGEG&therapy-identifier=http://example.nl/fhir/NamingSystem/pharmaceuticaltreatment|<id>"

  • "patient$get-aorta-data?context=MEDGEG&classifier=urn:oid:2.16.840.1.113883.2.4.4.8|<id>"

  • "patient$get-aorta-data?context=MEDGEG&instance-identifier=http://example.nl/fhir/NamingSystem/MedicationRequest|<id>"

De autorisatieserver retourneert, in de vorm van een JSON-array, een set van één of meerdere token responses.

Een token response bevat de volgende attributen (zie ook sectie 5 van RFC 6749) :

Parameter

Cardinaliteit

Toelichting

access_token

1..1

Een JWT-based AORTA access_token. Dit token is bedoeld voor een achterliggende GBx-server.

token_type 

1..1

Vaste waarde "Bearer".

expires_in 

1..1

Geldigheid in seconden van het uitgegeven AORTA access_token. Deze bedraagt 20 seconden.

scope 

1..1

Analoog aan de scope van een AORTA Token Exchange Response. De scope van een response (en van het afgegeven access_token) betreft de FHIR-interacties die deel uitmaken van de FHIR-operation/contextcode (en die ook daadwerkelijk worden ondersteund door de betreffende GBx-server).

Te hanteren error responses zijn eveneens beschreven in sectie 5 van RFC 6749.

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.

Stap

Omschrijving

Uitkomst

1

Het systeem ontvangt een verzoek en start de verwerking.

2

Het systeem controleert of het ontvangen request voldoet aan de AORTA interface specificaties.

Ongeldig verzoek

statuscode 400 Bad Request, error=invalid_request

Het systeem genereert de vereiste foutresponse en gaat verder met de exit stap van de main flow.

3

Het systeem controleert de geldigheid van het meegezonden AORTA access_token, zoals omschreven in de sectie "Toetsing AORTA access_token".

4

Het systeem bepaalt, m.b.v. de Selectie en Determinatie Interface welke interacties dienen te worden geïnitieerd (zie ook de toelichting “Gebruik van de SDS bij het bepalen van de interacties”).

Combinatie van operation, contextcode en rolcode niet gevonden

statuscode 400 Bad Request, error=invalid_request

Classifier in interactietabel heeft andere waarde in SDS

statuscode 500

Het systeem genereert de vereiste foutresponse en gaat verder met de exit stap van de main flow.

5

Het systeem bepaalt, voor iedere te initiëren interactie waarvan het protocol gelijk is aan het protocol van de interactie in de scope van het token request, m.b.v. feature getSourceInfo, welke GBZ-applicaties beschikken over gegevens die bij de betreffende interactie dienen te worden opgeleverd.

Wanneer getSourceInfo wordt uitgevoerd voor een specifieke source (URA of appID’s), dan kan het gebeuren dat de response geen dataCategories bevat. Dit heeft slechts gevolgen voor de attest claim van het uit te geven access_token, omdat geen toestemming kon worden vastgesteld. De betreffende appID('s) worden wel gewoon meegenomen in de volgende stap.

Wanneer getSourceInfo wordt uitgevoerd zonder een specifieke source mee te geven, dan zal de response ook voor iedere appID één of meerdere dataCategories bevatten.

Het appID van de Resource Client is opgenomen in de _vrb_client_id claim van het ontvangen AORTA access_token.

Doelsystemen kunnen niet worden bepaald

statuscode 500

Géén geschikt doelsysteem gevonden

statuscode 400, error=invalid_target

Het systeem genereert de vereiste foutresponse en gaat verder met de exit stap van de main flow.

6

Het systeem bepaalt, voor alle GBZ-applicaties die een interactie moeten ontvangen, danwel voor de gehele URA (bij gerichte operation aan een URA), m.b.v. de Routing Info Interface, welke interactie(s) precies kunnen en moeten worden geïnitieerd. Er wordt hierbij slechts routing info gevraagd voor interacties waarvan het protocol gelijk is aan het protocol van de interactie in de scope van het token request.

Deze info wordt gevraagd voor alle van SDS ontvangen FHIR- of v3-interacties. D.w.z., wanneer het te converteren access_token is uitgegeven voor een FHIR $get-aorta-data, dan wordt routing info gevraagd voor FHIR-interacties. Wanneer het te converteren access_token is uitgegeven voor een hybride generieke query, dan wordt routing info gevraagd voor v3-interacties.

Interactie(s) kunnen niet worden bepaald

statuscode 500

Het systeem genereert de vereiste foutresponse en gaat verder met de exit stap van de main flow.

7

Het systeem genereert het vereiste AORTA access_token, conform de hoogste versie die wordt ondersteund door de audience. Access_tokens mogen niet door het systeem worden opgeslagen. Voor de vulling van de scope van het access_token wordt gebruik gemaakt van classificerende attributen, zoals benoemd in de AORTA interactietabel, en indien van toepassing ook van te hanteren zoekparameters die zijn verkregen uit de SDS. Zie ook de “Toelichting vulling smart-on-fhir scope en _vrb_ter_scope in het AORTA access_token”.

8

<exit>

Het systeem retourneert een response naar de primaire actor.

GetTokenRequest

Feature

GetTokenRequest

Type

Service

Versie

2.0.1

Groep

Autorisatie

Gepubliceerd

Delta

Toegevoegd dat uitgaande requests en ontvangen responses ook moeten worden gelogd in de componentenlog.

Use case

AOF.UC.ASZA.100.v3

Feature

Versie

Dependency

Aanbieder

Afnemer

GetTokenRequest

2.0.1

AORTA Stelseltoken

*

*

GetTokenRequest

2.0.1

AORTA-ID HTTP Header

*

*

GetTokenRequest

2.0.1

Formaat AORTA interactietabel

*

-

GetTokenRequest

2.0.1

AORTA access_token

Verplicht >=4.*

-

GetTokenRequest

2.0.1

getSourceInfo

1

-

Inhoud en formaat van een getTokenRequest

Middels deze generieke interface kan een AORTA access_token worden verkregen voor één of meerdere interacties. Deze interface is slechts benaderbaar voor VZVZ-componenten, en dus niet voor GBx-applicaties. GBx-applicaties gebruiken de AORTA Token Exchange Interface.

Ondersteunde versies (ver attribuut) van het AORTA access_token zijn:

  • 1.1

  • 2.0

  • 3.2

  • 4.0

Op deze interface wordt een AORTA access_token geretourneerd conform de hoogste versie die de uiteindelijke bestemming van een interactie ondersteund.

Een getTokenRequest wordt op de volgende wijze verzonden:

POST [base endpointadres]/getTokenRequest/v2

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

Feature

AORTA-ID HTTP Header

Type

Subfeature

Versie

1.0.0

Groep

HTTP Headers

Gepubliceerd

Delta

Initiële versie van feature.

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 getTokenRequest is:

JSON
{
  "client": {
    "organisationId": "",
    "applicationId": ""
  },
  "destination": {
    "organisationId": "",
    "applicationId": ""
  },
  "scope": "",
  "patient": "",
  "start": "",
  "authzBase": "",
  "user": {
    "userId": "",
    "userRole": ""
  }
}

Input parameters:

Name

Cardinality

Type

Toelichting

client

1..1

Object

Informatie over de client (GBx) die een interactie wil initiëren.

client.organisationId

1..1

String

URA of AORTA organisatie-id.

Formaat van een URA:

  • "urn:oid:2.16.528.1.1007.3.3.<URA>"

Formaat van een AORTA Organisatie-id:

  • "urn:oid:2.16.840.1.113883.2.4.3.11.25.<org-id>"

client.applicationId

1..1

String

Het appID.

Formaat van een applicatie-id:

  • "urn:oid:2.16.840.1.113883.2.4.6.6.<applicatie-id>"

destination

1..1

Object

Informatie over de beoogde bestemming van de interactie.

destination.organisationId

0..1

String

URA of AORTA organisatie-id.

Verplicht wanneer een access_token wordt gevraagd voor een interactie, via het GTK, met een zorgaanbieder buiten AORTA.

Ook verplicht wanneer door een extern GTK een access_token wordt gevraagd voor een interactie, via het GTK, met een zorgaanbieder binnen AORTA.

Formaat van een URA:

  • "urn:oid:2.16.528.1.1007.3.3.<URA>"

Formaat van een AORTA Organisatie-id:

  • "urn:oid:2.16.840.1.113883.2.4.3.11.25.<org-id>"

destination.applicationId

0..1

String

Het appID.

Verplicht indien geen organisationId is meegegeven.

Formaat van een applicatie-id:

  • "urn:oid:2.16.840.1.113883.2.4.6.6.<applicatie-id>"

scope

0..1

String

Verplicht aanwezig indien géén authzBase wordt meegestuurd.

Voor vulling: zie scope bij tokenExchangeRequest.

patient

1..1

String

Het BSN van de patient.

Formaat van een burgerservicenummer:

  • "urn:oid:2.16.840.1.113883.2.4.6.3.<BSN>"

start

0..1

String

Tijdstip waarop het AORTA access_token geldig moet worden (aantal seconden sinds 1970-01-01T0:0:0Z gemeten in UTC).

Indien afwezig, dan wordt de huidige tijd genomen.

authzBase

0..1

String

Een eventueel gehanteerde authorization_base (Twiin) of AORTA consent_token, waarmee de destination van de interactie kan bepalen of er sprake is van veronderstellende toestemming van de patiënt voor de gevraagde interactie(s).

user

0..1

Object

Informatie over de verantwoordelijk gebruiker voor de interactie.

Slechts aanwezig indien noodzakelijk voor het vereiste vertrouwensniveau voor de interactie(s).

user.userId

1..1

String

ID van de gebruiker. UZI-nummer indien het een gebruiker binnen een AORTA GBx betreft.

In andere situaties betreft het een opaque ID.

Formaat van een UZI-nummer:

  • "urn:oid:2.16.528.1.1007.3.1.<UZI-nummer>", of

  • "http://fhir.nl/fhir/NamingSystem/uzi-nr-pers|<UZI-nummer>"

user.userRole

1..1

String

Rolcode van de gebruiker.

Formaat van een UZI-rolcode:

  • "urn:oid:2.16.840.1.113883.2.4.15.111.<UZI-rolcode>", of

  • "http://fhir.nl/fhir/NamingSystem/uzi-rolcode|<UZI-rolcode>"

Inhoud en formaat van een getTokenResponse

Een getTokenResponse bevat dezelfde attributen als een tokenExchangeResponse. De error responses en HTTP statuscodes die worden geretourneerd zijn eveneens gelijk aan die bij een tokenExchangeResponse.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.