Use Cases Resource Broker Common

Use Cases Extensions

Inhoudelijke toetsing request

Toetsing tokens bij inkomend request

Toetsing van een intern RB-request

Toetsing scope van request

Adressering van request

Screening van response

Toetsing van tokens

Toetsing MedMij access_token

De public key waarmee de digitale handtekening kan worden gecontroleerd wordt conform RFC 7517, als een JWK beschikbaar gesteld. De URL van waarop de JWK Set kan worden opgevraagd (jwks_uri) is opgenomen in de metadata van de autorisatieserver, die via de AS Metadata Interface, conform RFC 8414 kan worden opgehaald via <iss>/.well-known/oauth-authorization-server. 

De iss van het token is opgenomen in het token zelf, maar wordt vanwege security redenen ook out-of-band bij de resource server aangemerkt als een vertrouwde issuer. Het systeem mag geen tokens verwerken van niet-vertrouwde issuers.

Iedere JSON Web Key (JWK) in de set 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, en waarvan het kty attribuut gelijk is aan "RSA" en het use attribuut gelijk is aan "sig".

Uit te voeren controles m.b.t. het  access_token:

1. de juistheid van de digitale handtekening (signature), inclusief de geldigheid van het certificaat waarmee de handtekening is geplaatst. Hierbij worden ook maatregelen genomen om bedreiging 2.1 uit RFC 8725 tegen te gaan.

2. het access_token mag niet verlopen zijn (exp claim).

3. het access_token moet zijn uitgegeven door de Autorisatie Server van LSP+ (iss claim).

Toetsing DigiD Authenticatietoken

Het DigiD authenticatietoken is een SAML Assertion, met daarin ondermeer de volgende elementen en attributen die informatie bevatten over de geldigheid ervan:

• Conditions.NotBefore en Conditions.NotOnOrAfter - Bevat de geldigheid van de Assertion, bij DigiD gesteld op -2 en +2 minuten vanaf het verzendmoment. Dit is de geldigheid voor het verwerken van de SAML-Assertion. Deze elementen hoeven niet te worden gecontroleerd.

• Subject.SubjectConfirmationData.NotOnOrAfter - Bevat volgens de SAML-standaard: "A time instant at which the subject can no longer be confirmed." Bij DigiD valt deze samen met Conditions.NotOnOrAfter. Dit element hoeft niet te worden gecontroleerd.

• AuthnStatement.@AuthnInstant - Het moment waarop de eindgebruiker zich heeft geauthentiseerd bij DigiD. Dit tijdstip Dit tijdstip valt vaak samen met of net voor Assertion.@IssueInstant.

Het systeem dient, m.b.t. het DigiD authenticatietoken, de volgende checks uit te voeren:

1. Juistheid van de digitale handtekening.

2. Is het token uitgegeven door DigiD (Assertion.Issuer).

3. Bij interactie vanuit MedMij (LSP+): is het token bedoeld voor de Autorisatie Server MedMij component (Assertion.AudienceRestriction.Audience).

4. Bij interactie vanuit GBP: is het token bedoeld voor Volgjezorg (Assertion.AudienceRestriction.Audience).

5. Bij interactie vanuit GBP: heeft authenticatie van de gebruiker voldoende recent plaatsgevonden, d.w.z. AuthnStatement.@AuthnInstant > (<huidige tijd> - <gracetime>). De te hanteren gracetime in minuten, moet per use case geconfigureerd kunnen worden. Dit deel van de check moet per use case, via de configuratie, ook uitgezet kunnen worden.

Ondersteunde use cases zijn:

1. Interactie vanuit GBP (Volgjezorg);

2. Interactie vanuit MedMij (LSP+).

Toetsing AORTA access_token

Het JWT-based access_token wordt op basis van RS256 (RSA Signature met SHA-256), digitaal ondertekend met de private key van de Autorisatie Server. De public key waarmee de digitale handtekening kan worden gecontroleerd wordt conform RFC 7517, als een JWK beschikbaar gesteld.

De URL van waarop de JWK Set kan worden opgevraagd (jwks_uri) is opgenomen in de metadata van de autorisatieserver, die via de AS Metadata Interface, kan worden opgehaald.

De iss van het token is opgenomen in het token zelf, maar wordt vanwege security redenen ook via het AORTA Stelseltoken bij de resource server aangemerkt als een vertrouwde issuer. De resource server mag geen tokens verwerken van niet-vertrouwde issuers. De resource server moet controleren dat de waarde van <iss> overeenkomt met de waarde van issuer in de ontvangen metadata.

Iedere JSON Web Key (JWK) in de set 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, en waarvan het kty attribuut gelijk is aan "RSA" en het use attribuut gelijk is aan "sig".

De scope van een access_token kan meerdere interacties omvatten, die ook na elkaar kunnen worden uitgevoerd. Het systeem moet het daarom toestaan wanneer eenzelfde access_token meerdere malen wordt gebruikt.

Het systeem toetst:

1. Of het de gehanteerde versie van het token ondersteunt.

2. Of het token is uitgegeven door een voor mij vertrouwde partij (issuer, in dit geval door de Autorisatie Server MedMij of door de Autorisatie Server ZA), vertrouwde autorisatieservers zijn opgenomen in het AORTA Stelseltoken.

3. De juistheid van de digitale handtekening (signature), inclusief de geldigheid van het certificaat waarmee de handtekening is geplaatst. Hierbij worden ook maatregelen genomen om bedreiging 2.1 uit RFC 8725 tegen te gaan.

4. Of het het token wordt gebruikt door de partij (resource client) aan wie het is uitgegeven.

   • JWT-based access_token: via controle van de _vrb_client_id claim in combinatie met de geauthentiseerde TLS-client.

5. Of het token mag worden geconsumeerd.

   • JWT-based access_token: via controle van de _vrb_aud claim en van de aud claim (voor interactie gericht aan een Resource Broker component)

6. Of de geldigheidsduur van het token niet is verstreken. Met betrekking tot het ingangstijdstip dient, wanneer problemen ontstaan door tijdsynchronisatie, een gracetime te kunnen worden gehanteerd. Deze bedraagt maximaal 15 seconden. Aanbevolen wordt om deze gracetime configureerbaar te maken.

7. Bij interactie door patiënt (te zien aan de role claim van het access_token):

   • JWT-based access_token: is de inhoud van de patient claim gelijk aan de inhoud van de sub claim.

   Toelichting: omdat machtigingen/mandateringen nog niet worden ondersteund, mag de sub claim niet afwijken van de patient claim, en moet een token, wanneer dit wel het geval is, worden beschouwd als "invalid".

Toetsing van samenhang tussen tokens

Samenhang tussen AORTA access_token en DigiD-token:

• is Subject.NameID (het gedeelte dat de BSN van de gebruiker bevat) in het DigiD-token gelijk aan de BSN in de sub claim van het access_token;

Toelichtingen

Bepalen van het interactie-id

De _vrb_ter_scope claim in het AORTA access_token, bevat al een volledig interactie-id die wordt ondersteund door de client. Het is natuurlijk niet zeker dat de client deze interactie ook daadwerkelijk initieert, maar voor de profileVersion mag op het access_token worden vertrouwd.

Om het interactie-id te bepalen van de daadwerkelijk geïnitieerde interactie, moet het systeem de waarden van een aantal velden, waarop kan worden gezocht in de AORTA-interactietabel, vaststellen:

1. interactionType - te bepalen uit de HTTP method in combinatie met de URL, zie ook https://hl7.org/fhir/http.html#summary.

2. protocol en protocolVersion - te bepalen m.b.v. het endpoint adres waarop het request is ontvangen.

3. profile OF resourceType + classifier

   1. profile - bij POST interacties van transaction Bundles die een specifiek FHIR-profiel hanteren, wordt deze verplicht meegezonden in het meta.profile attribuut van de betreffende Bundle.

   2. resourceType - te bepalen m.b.v. de URL of m.b.v. de ontvangen HTTP body.

   3. classifier - te bepalen m.b.v. de URL of m.b.v. de ontvangen HTTP body.

4. profileVersion - te bepalen met de inhoud van de AORTA-Version header en/of o.b.v. de _vrb_ter_scope claim in het AORTA access_token.

Controle van batch en transaction requests

Wanneer een batch of een transaction Bundle wordt ontvangen, dan dienen controles plaats te vinden per entry in de Bundle. De afhandeling bij detectie van een niet-conformiteit is voor batches anders dan voor transactions.

Wanneer een batch is ontvangen waarvan één of meerdere entries niet door de controles komen, dan stelt het systeem vast welke foutmelding later dient te worden toegevoegd aan de response en verwijdert het systeem de foutieve entries uit de batch die wordt doorgestuurd. Een batch dient te worden doorgestuurd zolang het tenminste één geldige en toegestane entry bevat.

Wanneer een transactie is ontvangen waarvan één of meerdere entries niet door de controles komen, dan stelt het systeem vast welke foutmelding dient te worden toegevoegd aan de response en retourneert het direct een response. Een transaction mag slechts worden doorgestuurd wanneer alle entries geldig zijn en ook zijn toegestaan.

Controle of request binnen scope valt

Wanneer een request wordt ontvangen dan moet worden getoetst of dit request binnen de aangegeven scope valt, d.w.z.:

• maakt het request deel uit van de gebruikte gegevensdienst (MedMij), of

• past het request binnen de scope van het AORTA access_token (AORTA).

Indien een request het BSN van een patiënt bevat, dan dient ook te worden getoetst of deze overeenkomt met het BSN waarvoor het gehanteerde access_token is uitgegeven.

Indien de URL van het request een app-id bevat, dan dient te worden getoetst of deze tot de audience van het meegezonden AORTA access_token behoort.

Bij deze toetsing wordt altijd rekening gehouden met de gehanteerde HTTP operatie (bijv. GET) en met het gehanteerde FHIR resourcetype (bijv. MedicationRequest).

Bij sommige FHIR resourcetypes spelen ook de gehanteerde (classificerende) zoekparameters een rol. Dit is bijvoorbeeld het geval bij CarePlan, Consent, DocumentManifest, DocumentReference, MedicationDispense, MedicationRequest en Observation.

Bepalen benodigde interactie(s) en versie(s)

Wanneer een (FHIR-)interactie wordt ontvangen, dan dient te worden bepaald met welke AORTA FHIR-interactie-id('s) en versie(s) de ontvangen interactie kan worden verwerkt. De juiste AORTA interactie(s) en versie(s) kunnen worden gevonden in het de AORTA Interactietabel. Zie ook https://www.hl7.org/fhir/http.html#summary voor de wijze waarop voor een HTTP-aanroep kan worden vastgesteld om welke FHIR interactie type het gaat, bijvoorbeeld "read" of "create".

Een voorbeeld. Stel de volgende FHIR-interactie wordt ontvangen:

• GET [base]/Observation/$lastn?code=http://snomed.info/sct|365508006 , welke is voorzien van een MedMij access_token die is afgegeven voor de scope van gegevensdienst 48

In het overzicht van interacties, versies en systeemrollen kan dan worden gevonden dat

• de corresponderende AORTA FHIR-interactie en conformance "search:zib-LivingSituation:2" is (de vereiste versie van de interactie is derhalve "2.x")

Wanneer Resource Broker ZA-in of Resource Broker MedMij-in een AORTA FHIR-interactie initieert op Resource Broker VnC, dan dient de AORTA-Version header op de juiste wijze te worden gevuld. 

De contentVersion geeft aan welke versie van de interactie Resource Broker ZA-in of Resource Broker MedMij-in zelf hanteert richting Resource Broker VnC. Aangezien Resource Broker ZA-in of Resource Broker MedMij-in een interactie niet vertaalt, is dit altijd dezelfde versie als degene die werd ontvangen.

De acceptVersion geeft aan welke versie van de interactie mag worden gehanteerd door het reagerend GBZ (het reagerend GBZ zou immers meerdere versies van een interactie kunnen ondersteunen). Aangezien Resource Broker VnC (nog) geen conversie uitvoert van verschillende versies van interacties, dient de acceptVersion te worden gevuld met de major versie van de contentVersion. Wanneer in de contentVersion bijvoorbeeld wordt gebruikt "1.0", dan dient in de acceptVersion te worden gehanteerd "1", "1.x" of "1.*".

In het voorbeeld hierboven zou de contentVersion worden gevuld met "1.0" en zou de acceptVersion worden gevuld met "1" of "1.x". De contentVersion in de response header die wordt ontvangen van Resource Broker VnC zou een waarde moeten hebben die aangeeft dat inderdaad major versie "1" is gehanteerd.

Toetsing systeemrollen en conformances

Naast het bepalen van de juiste inhoudelijke conformanceregels dient, wanneer een request is ontvangen vanuit MedMij, te worden getoetst of de applicatie van de zorgaanbieder geschikt en bereid is om interacties te ontvangen in het kader van MedMij, d.w.z. of de applicatie beschikt over de systeemrollen:

• MedMij Opleverend Systeem (vereist voor UC Verzamelen), danwel

• MedMij Ontvangend Systeem (vereist voor UC Delen)

Indien de interactie zal worden gebaseerd op FHIR, dan moet ook worden getoetst of de applicatie beschikt over systeemrol AORTA access_token Verwerkend Systeem.

Wanneer een batch Bundle wordt ontvangen, die bestaat uit meerdere requests, dan dient een applicatie tenminste geschikt te zijn om één van deze requests te verwerken. Wanneer een transactie Bundle wordt ontvangen, die bestaat uit meerdere requests, dan dient een applicatie geschikt te zijn om alle requests te verwerken.

Bepalen van de juiste appID's

De GBZ-applicatie, of de de GBZ-applicaties waaraan een interactie moet worden gericht wordt als volgt bepaald.

Indien de client de interactie al richtte aan één specifiek appID, dan hoeft slechts te worden getoetst of de betreffende GBZ-applicatie beschikt over de vereiste systeemrollen en conformances.

Filtering HTTP-response

Voor filtering van ontvangen HTTP statuscodes gelden de volgende regels:

• Wanneer een statuscode 403 wordt ontvangen, die is vergezeld van een OperationOutcome met issue.code=suppressed, dan wordt deze ongewijzigd doorgestuurd.

• Wanneer een statuscode 404 wordt ontvangen, dan wordt deze ongewijzigd doorgestuurd, inclusief de eventueel bijbehorende OperationOutcome.

• Wanneer een andere 4xx statuscode wordt ontvangen, dan wordt deze beschouwd als een generieke, fatale, "interne" fout in de resource broker. In deze situatie retourneert het systeem:
  

  statuscode 500 Internal Server Error

  • In deze situatie wordt, voor iedere resource server die een fout produceerde, een OperationOutcome toegevoegd met issue.severity "warning", issue.code "processing" en issue.diagnostics "<appID van betreffende resource server>".

  
  Een eventueel ontvangen WWW-Authenticate HTTP response header dient in deze situatie uit de response te worden verwijderd. In andere gevallen dient een eventueel ontvangen WWW-Authenticate header wel te worden geretourneerd.

De volgende HTTP response headers dienen ongewijzigd te worden geretourneerd:

• Last-Modified

• ETag

• Content-Type

Wanneer de Resource Client een systeem is die uitwisselt conform het AORTA afsprakenstelsel, dan worden ook de volgende HTTP response headers ongewijzigd geretourneerd:

• AORTA-Version

Een eventueel ontvangen Location header is in een eerdere stap van de flow reeds aangepast en dient in de gewijzigde vorm te worden geretourneerd.

Andere ontvangen HTTP response headers, dan de hierboven genoemde, worden niet overgenomen in de te retourneren HTTP response.

Eventueel ontvangen OperationOutcomes worden ongewijzigd geretourneerd.