Gemeenschappelijke Interface onderdelen (versie 0.6.12 - definitief)

Generieke eisen voor alle server-to-server interfaces

AOF.GS-I.GEN.100.v1

De volgende eisen gelden voor alle server-to-server interfaces:

HTTP-requests en -responses worden verzonden conform HTTP versie 1.1.
Alle HTTP-verkeer wordt verzonden binnen een TLS verbinding, waarbij verplicht gebruik wordt gemaakt van tweezijdige server authenticatie.
Uitzondering op bovenstaande eis
1. Op de AORTA CapabilityStatement Interface wordt slechts server authenticatie vereist, maar mag de resource server ook client authenticatie vereisen.
2. Op de AS Metadata Interface wordt slechts server authenticatie toegepast.
TLS clients en TLS servers dienen tenminste TLS versie 1.2 te ondersteunen en mogen hierbij slechts gebruik maken van een ciphersuite uit de categorie "Goed", zoals genoemd in bijlage C van de ICT-beveiligingsrichtlijnen voor Transport Layer Security (TLS).
TLS clients en TLS servers maken bij voorkeur echter gebruik van een hogere TLS versie.
Server authenticatie vindt plaats middels PKIo servercertificaten of, voor zorgaanbieders, m.b.v. UZI-servercertificaten.
Voor alle op FHIR gebaseerde interfaces gelden de generieke eisen uit de MedMij informatiestandaarden. Dit betekent ondermeer dat zowel JSON als XML moet worden ondersteund.

Inhoud en formaat van het MedMij access_token

AOF.TS.MAT.100.v1

Het MedMij access_token is een JWT, die bestaat uit een header, een payload en een signature, waarbij gebruik wordt gemaakt van JWS Compact Serialization.

AOF.TS.MAT.150.v1

De header van het token bevat de volgende attributen:

Claim	Vaste waarde	Toelichting
alg	RS256
typ	mat+JWT	"mat" is een afkorting voor MedMij access_token
kid	-	The identifier of the key-pair used to sign this JWT

AOF.TS.MAT.200.v1

Het access_token wordt op basis van RS256 (RSA Signature met SHA-256), digitaal ondertekend met de private key van de Autorisatie Server. De signature wordt geplaatst over de header en de payload.

AOF.TS.MAT.300.v1

Het access_token bevat de volgende payload:

Claim	Vaste waarde	Toelichting
jti	-	Unieke ID van het token
ver	1.0	De versie van de tokendefinitie die wordt gehanteerd
iss	-	HTTPS-URL van de Autorisatie Server voor deze versie van het MedMij afsprakenstelsel (interfaceversie)
exp	-	Gelijk aan de waarde van expires_in in het access token response bericht
scope	-	Gelijk aan de scope in het access token response bericht. Wanneer een access_token wordt gegenereerd t.b.v. een interne $is-allowed operation tussen Autorisatie Server en Resource Broker, dan wordt de scope gevuld met $is-allowed/ gevolgd door de scope in het access token response bericht Bijvoorbeeld: "$is-allowed/eenofanderezorgaanbieder~42"

Inhoud en formaat van het AORTA access_token

AOF.TS.AAT.100.v1

Het JWT-based AORTA access_token bestaat uit een header, een payload en een signature, waarbij gebruik wordt gemaakt van JWS Compact Serialization.

AOF.TS.AAT.200.v1

De header van het token bevat de volgende attributen:

Claim

Vaste waarde

Toelichting

alg

RS256

typ

att+JWT

"att" is een afkorting voor AORTA transactietoken, d.w.z. de voormalige naam van het AORTA

access_token. In een latere versie zal deze naam worden aangepast naar "aat+JWT".

kid

-

The identifier of the key-pair used to sign this JWT

AOF.TS.AAT.300.v1

Het token wordt op basis van RS256 (RSA Signature met SHA-256), digitaal ondertekend met de private key van de Autorisatie Server. De signature wordt geplaatst over de header en de payload.

AOF.TS.AAT.400.v1

De payload van het token is omschreven in onderstaande tabel.

Claim	Vaste waarde	Toelichting
jti	-	jti bevat een globaal uniek ID van het betreffende token. Aanbevolen wordt om een UUID te gebruiken.
iat	-	iat bevat het tijdstip van uitgifte van dit token (aantal seconden sinds 1970-01-01T0:0:0Z gemeten in UTC).
iss	-	iss bevat de HTTPS-URL van de autorisatieserver die het token heeft uitgegeven. Omdat voor iedere versie van het MedMij afsprakenstelsel unieke endpoint adressen gelden, bevat deze URL ook de versie van het MedMij afsprakenstelsel. Op deze manier kan per versie van het afsprakenstelsel, automatisch de juiste metadata, met daarin de juiste endpoints worden opgehaald.
sub	-	Formaat: "<id-systeem>\|<id>" De (reeds geauthentiseerde) gebruiker die uitgifte van dit token legitimeert. In dit geval de persoon die haar eigen gegevens opvraagt. sub bevat de string "http://fhir.nl/fhir/NamingSystem/bsn\|<bsn>". Het id-systeem is nodig, omdat in een volgende fase ook UZI-nummers kunnen worden gecommuniceerd.
role	-	Formaat: "<codesysteem>\|<rolcode>" role bevat de rolcode die hoort bij "patiënt", dus "http://fhir.nl/fhir/NamingSystem/aorta-rolcode\|P". Het id-systeem is nodig, omdat in een volgende fase ook UZI-rolcodes kunnen worden gecommuniceerd.
nbf	-	nbf bevat het tijdstip van uitgifte van dit token (aantal seconden sinds 1970-01-01T0:0:0Z gemeten in UTC).
exp	-	exp wordt gevuld met de expiration time van het MedMij access_token die wordt ingewisseld voor dit AORTA access_token.
aud	-	Formaat: ["<appID>", "<appID>"] De aud van het token bevat de set van appID's van alle GBx-applicaties, die deze interactie gaan ontvangen. Een appID heeft het formaat: "urn:oid:2.16.840.1.113883.2.4.6.6.<applicatie-id>". Aan iedere GBx-applicatie die is aangesloten op AORTA wordt een eigen <applicatie-id> toegekend.
scope	-	Voor de juiste vulling zie tekst onder deze tabel.
patient	-	Formaat: "<id-systeem>\|<id>" Het BSN van de patiënt, d.w.z. de persoon waarop de gegevens, die worden uitgewisseld, betrekking hebben. patient bevat de string "http://fhir.nl/fhir/NamingSystem/bsn\|<bsn>". De verwachting is weliswaar dat hier altijd BSN's gecommuniceerd gaan worden. Het id-systeem is hier toegevoegd om consistent te blijven met de sub claim en om eventueel ook eigen patient-ID's van een zorgaanbieder te kunnen ondersteunen.
client_id	-	Formaat: "urn:oid:2.16.840.1.113883.2.4.6.6.<applicatie-id>" De client_id claim bevat het appID van het LSP. Dit attribuut bevat informatie over de partij die als resource client mag optreden en daarvoor dit token mogen gebruiken.
_vrb _vrb_aud _vrb_client_id _vrb_ion	-	De _vrb claim bevat, in een aantal subclaims, VZVZ Resource Broker specifieke informatie over de afhandeling van interacties. Een resource server (GBZ-applicatie) mag deze claim desgewenst negeren. _vrb_aud bevat het appID van het LSP. Formaat: "urn:oid:2.16.840.1.113883.2.4.6.6.<applicatie-id>". _vrb_client_id bevat het appID van de MedMij resource server van LSP+, die jegens het LSP optreedt als resource client. Formaat: "urn:oid:2.16.840.1.113883.2.4.6.6.<applicatie-id>". _vrb_ion bevat de naam van de organisatie die die het request heeft geïniteerd (de "initiating organisation name"). In de MedMij use case gaat het om de OAuthclientOrganisatienaam (naam van het PGO), zoals opgenomen in de MedMij OCL.
ver	1.1	De versie van de tokendefinitie die wordt gehanteerd.

AOF.TS.AAT.500.v1

De scope claim van het token wordt als volgt gevuld:

Gegevensdienst / Interactie	Vulling van scope
Verzamelen Afspraken 2.0	patient/Appointment.read medmij.gegevensdienst.47
Verzamelen Basisgegevens zorg 3.0	patient/Patient.read patient/Coverage.read patient/Consent.read patient/Condition.read patient/Observation.read patient/NutritionOrder.read patient/Flag.read patient/AllergyIntolerance.read patient/MedicationStatement.read patient/MedicationRequest.read patient/MedicationDispense.read patient/DeviceUseStatement.read patient/Immunization.read patient/Procedure.read patient/Encounter.read patient/ProcedureRequest.read patient/ImmunizationRecommendation.read patient/DeviceRequest.read patient/Appointment.read medmij.gegevensdienst.48
Verzamelen Basisgegevens GGZ 2.0	patient/Patient.read patient/Coverage.read patient/Consent.read patient/Condition.read patient/Observation.read patient/CarePlan.read patient/Procedure.read patient/DiagnosticReport.read patient/CareTeam.read medmij.gegevensdienst.50
Verzamelen Documenten 3.0	patient/DocumentManifest.read patient/DocumentReference.read patient/Binary.read medmij.gegevensdienst.51
Delen Meetwaarden vitale functies 2.0	patient/Observation.write medmij.gegevensdienst.53
Verzamelen Meetwaarden vitale functies 2.0	patient/Observation.read medmij.gegevensdienst.52
Verzamelen verwijzingen naar vragenlijsten 2.0	patient/Task.read medmij.gegevensdienst.59
Delen antwoorden op vragenlijsten 2.0	patient/Task.write patient/QuestionnaireResponse.write medmij.gegevensdienst.60
$is-allowed	patient$is-allowed

Mapping tussen OID en FHIR-based namingsystems

Onderstaande tabel bevat een mapping van de binnen AORTA on FHIR gehanteerde namingsystems.

OID	URI	Description
2.16.840.1.113883.2.4.6.3	http://fhir.nl/fhir/NamingSystem/bsn	Burgerservicenummer
2.16.528.1.1007.3.1	http://fhir.nl/fhir/NamingSystem/uzi-nr-pers	Uniek Zorgverlener Identificatienummer Personen
2.16.528.1.1007.3.2	http://fhir.nl/fhir/NamingSystem/uzi-nr-sys	UZI nummer van systeem, gekoppeld aan UZI services certificaat
2.16.528.1.1007.3.3	http://fhir.nl/fhir/NamingSystem/ura	UZI-register abonneenummer
2.16.840.1.113883.2.4.3.11.8	http://fhir.nl/fhir/NamingSystem/aorta-rolcode	Zie: https://www.nictiz.nl/wp-content/uploads/OID-ovrzicht-150819.pdf
2.16.840.1.113883.2.4.3.11.25	-	Organisatie-id in het kader van AORTA.
2.16.840.1.113883.2.4.6.3	http://fhir.nl/fhir/NamingSystem/bsn	Burgerservicenummer
2.16.840.1.113883.2.4.6.6	http://fhir.nl/fhir/NamingSystem/aorta-app-id	Applicatie ID binnen de AORTA infrastructuur
2.16.840.1.113883.2.4.15.4	http://fhir.nl/fhir/NamingSystem/aorta-gegevenssoort	AORTA gegevenssoort
2.16.840.1.113883.2.4.15.111	http://fhir.nl/fhir/NamingSystem/uzi-rolcode	UZI rolcode

HTTP-response

AOF.GS-I.HTR.100.v1

Wanneer een resource server een uitzondering/foutsituatie detecteert, dan dient het dit aan te geven in de HTTP-response. Een uitzondering kan op een aantal verschillende manieren worden gecommuniceerd, vaak ook middels een combinatie ervan:

De HTTP statuscode;
Een HTTP Authenticate response header;
Een FHIR OperationOutcome, met hierin ondermeer de volgende attributen
- issue.severity (verplicht);
- issue.code (verplicht);
- issue.details (optioneel in FHIR, maar indien aangegeven in onderstaande tabel verplicht te vullen conform de aangegeven valueset;
- issue.diagnostics (optioneel in FHIR, optioneel binnen AORTA, waarbij altijd de beveiliging van de resource server in ogenschouw moet worden genomen).

De resource server retourneert fouten conform https://informatiestandaarden.nictiz.nl/wiki/MedMij:V2020.01/FHIR_IG#Handling_errors en http://hl7.org/fhir/STU3/search.html#errors. De te retourneren HTTP statuscode en mee te sturen aanvullende informatie, is opgenomen in onderstaande tabel.

In de bijbehorende use cases is gespecificeerd welke situaties gedetecteerd dienen te worden. Niet alle situaties zijn van toepassing op iedere use case.

Gedetecteerde situatie	Response
Succes	statuscode 200
Resource broker success	statuscode 200 Wanneer één of meerdere van de achterliggende resource servers een fout heeft geretourneerd (anders dan het niet voldoen aan de MedMij beschikbaarheidsvoorwaarde), dan wordt voor ieder van deze resource servers een OperationOutcome toegevoegd met issue.severity "`warning`", issue.code "`processing`" en issue.diagnostics "`<de betreffende appID>`".
Ongeldig verzoek (de ontvangen interactie is ongeldig, voldoet niet aan de specificaties - deze situatie kan ook ontstaan doordat een verplichte header ontbreekt of ongeldig is)	statuscode 400 Wanneer een verplichte FHIR zoekparameter ontbreekt, dan wordt een OperationOutcome met issue.code "`required`" en de van toepassing zijnde issue.details geretourneerd Wanneer een FHIR zoekparameter een ongeldige waarde heeft, dan wordt een OperationOutcome met issue.code "`value`" en de van toepassing zijnde issue.details geretourneerd; Bij ontvangst van een FHIR zoekparameter die niet is gespecificeerd binnen de gegevensdienst wordt een OperationOutcome met issue.code "`not-supported`" en de van toepassing zijnde issue.details geretourneerd. Wanneer een ontvangen resource instance ongeldig is, dan wordt een OperationOutcome met issue.code "`invalid`" en de van toepassing zijnde issue.details geretourneerd. In deze situatie wordt, conform RFC 6750, ook een `WWW-Authenticate` HTTP response header met als auth-scheme "`Bearer`" en een `error` attribuut met waarde "`invalid_request`" geretourneerd.
Een verplicht token ontbreekt	statuscode 401 In deze situatie wordt geen nadere informatie over de opgetreden fout geretourneerd.
Ongeldig token (een ontvangen token is niet geldig, of kan niet worden gevalideerd)	statuscode 401 In deze situatie wordt, conform RFC 6750, ook een `WWW-Authenticate` HTTP response header met als auth-scheme "`Bearer`" en een `error` attribuut met waarde "`invalid_token`" geretourneerd. In deze situatie mag daarnaast ook een OperationOutcome met issue.code "`security`" worden geretourneerd.
Request van deze client mag niet worden verwerkt, bijvoorbeeld "de PGO server komt niet voor op de MedMij whitelist".	statuscode 403 In deze situatie wordt geen nadere informatie over de opgetreden fout geretourneerd.
De client beschikt niet over de juiste autorisatie, bijvoorbeeld een xIS probeert een TKID te activeren voor een ander xIS. mismatch tussen BSN in AORTA access_token en BSN in ontvangen gegevens.	statuscode 403 Indien een `Authorization` header werd gebruikt in het request, dan wordt in deze situatie, conform RFC 6750, een `WWW-Authenticate` HTTP response header met als auth-scheme "`Bearer`" en een `error` attribuut met waarde "`access_denied`" geretourneerd. Indien het een FHIR-request betreft, dan wordt in deze situatie (ook) een OperationOutcome met issue.code "`forbidden`" geretourneerd.
Niet voldaan aan (MedMij) beschikbaarheidsvoorwaarde	statuscode 403 In deze situatie wordt, conform RFC 6750, een `WWW-Authenticate` HTTP response header met als auth-scheme "`Bearer`" en een `error` attribuut met waarde "`access_denied`" geretourneerd. In deze situatie wordt een OperationOutcome met issue.code "`suppressed`" geretourneerd.
Scope niet toereikend voor interactie	statuscode 403 In deze situatie wordt, conform RFC 6750, ook een `WWW-Authenticate` HTTP response header met als auth-scheme "`Bearer`" en een `error` attribuut met waarde "`insufficient_scope`" geretourneerd. In deze situatie mag daarnaast ook een OperationOutcome met issue.code "`forbidden`" of "`security`" worden geretourneerd.
FHIR resourcetype is niet gespecificeerd binnen de gegevensdienst of wordt niet ondersteund	statuscode 404 In deze situatie wordt een OperationOutcome met issue.code "`not-supported`" en de van toepassing zijnde issue.details geretourneerd.
resource-id niet bekend	statuscode 404 In deze situatie wordt een OperationOutcome met issue.code "`not-found`" en de van toepassing zijnde issue.details geretourneerd.
Gevraagde acceptVersion in de AORTA-Version header wordt niet ondersteund	statuscode 406
Gehanteerde contentVersion in de AORTA-Version header wordt niet ondersteund	statuscode 415
Fout in server	statuscode 500
Fout in achterliggende server	statuscode 500 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>`".