Resource Broker Interfaces (versie 0.6.18 - definitief)

Resource Broker Common

AORTA FHIR Resource Broker Interface

Generiek

AOF.RB-I.ASF.100.v1

De AORTA Resource Broker Interface is nagenoeg gelijk aan de AORTA Resource Interface. Dit geldt zowel voor het generieke deel van de interface als voor de AORTA FHIR * interacties. In deze sectie worden daarom slechts de afwijkingen hierop beschreven.

M.b.t. de HTTP headers die worden gebruikt geldt voor alle interacties de volgende uitzondering:

• In de Authorization header wordt een MedMij access_token meegestuurd
  Authorization: Bearer <medmij_access_token>
• Tevens zal het, van DigiD ontvangen, authenticatietoken (Assertion), base64url gecodeerd conform RFC 4648) als volgt worden toegevoegd aan ieder request:
  DigiD-Authenticatie: SAML2-Bearer <DigiD SAML Assertion>

Doordat de DigiD Assertion wordt verstuurd in een HTTP-header met als naam DigiD-Authenticatie en met een auth_scheme SAML2-Bearer, weet de ontvanger al voor decodering van het token, dat het een op XML-gebaseerde SAMLv2 Assertion betreft, die moet voldoen aan de schema-definitie van DigiD.

Resource Broker MedMij-in

MedMij CapabilityStatement Interface

AOF.RB-I.MMC.100.v1

Resource broker biedt op zijn endpoint een CapabilityStatement aan. Een resource client kan het statement als volgt bij de resource broker opvragen:

GET [base]/metadata {?_format=[mime-type]}

De waarde van [base] is gelijk aan de in de MedMij ZAL geregistreerde ResourceEndpointUri.

Het gaat hier om een CapabilityStatement van het type "Instance", oftewel het bevat informatie over de daadwerkelijke installatie die benaderbaar is. Bovenstaande capabilities interactie is binnen FHIR verplicht voor FHIR servers.

Deze interface maakt deel uit van de resource interface, zoals gespecificeerd in het MedMij afsprakenstelsel. Op deze interface worden de additionele HTTP headers, zoals de Authorization header en de MedMij-Request-ID header, echter NIET toegepast.

MedMij FHIR Resource Broker Interface

Generiek

AOF.RB-I.MMF.100.v1

Resource broker biedt de resource interface, zoals gespecificeerd in het MedMij afsprakenstelsel. De resource broker biedt gedurende sommige perioden meerdere endpoints, d.w.z. één per actieve release van het MedMij afsprakenstelsel. 

Verschil in resource interface tussen MedMij 1.2.0 en 1.3.0

Het MedMij afsprakenstelsel introduceert de HTTP header MedMij-Request-ID. Dit heeft tot gevolg dat deze header moet worden gecontroleerd (uitzondering indien afwezig) en ook moet worden gebruikt in de AORTA-ID header en in de logging van LSP+.

Ondersteunde MedMij gegevensdiensten

AOF.RB-I.OMG.100.v1

Resource broker ondersteunt de volgende MedMij gegevensdiensten:

De kolommen voor de aantallen interacties bevatten het maximum aantal interacties dat per persoon zal worden geïniteerd om de gehele use case één maal te doorlopen.

RS-logging Interface

AOF.RB-I.RSL.100.v1

Logbestanden die nodig zijn voor de managementrapportages kunnen, conform gemaakte afspraken in het DAP, middels een API, via HTTPS (TLS) door VZVZ-beheer worden opgehaald. Technisch formaat van de logbestanden is JSON.

De logging kan desgewenst worden opgesplitst in meerdere JSON-bestanden. Ieder JSON-bestand heeft wel altijd betrekking op interacties die plaats hebben gevonden conform één specifieke MedMij-release. Op deze manier kan in de rapportages een beeld worden gecreëerd van het gebruik van een bepaalde MedMij-release in de tijd.

De volgende loggegevens moeten beschikbaar worden gesteld:

Resource Broker APR

Applicatie Register Interface

Generiek

Bij alle interacties die worden geboden door de applicatie register interface worden de volgende HTTP headers toegepast:

• Bij iedere interactie wordt in ieder HTTP-request, op de volgende wijze, een custom HTTP header meegezonden:
  AORTA-ID: initialRequestID=<UUID conform RFC4122>; requestID=<UUID conform RFC4122>
• Bij iedere interactie wordt in het HTTP-request op de volgende wijze een custom HTTP header meegezonden, met daarin de versie van de betreffende interactie die wordt gehanteerd in het request en de versie of versies die door de resource broker mogen worden gehanteerd bij de verwerking van de interactie:
  AORTA-Version: contentVersion=<versienummer>; acceptVersion=<versienummer>
• Bij iedere interactie wordt in de HTTP-response op de volgende wijze een custom HTTP header meegezonden met daarin de door resource broker daadwerkelijk gehanteerde versie:
  AORTA-Version: contentVersion=<versienummer>
  

TKID-activatie

Resource broker biedt een interactie aan, waarmee één of meerdere TKID's voor een xIS-instantie, op een aangegeven base endpointadres,  kunnen worden geactiveerd:

POST [base endpointadres van het LSP]/activate
Content-Type: application/json

{

"app-id": "<app-id>",

"tkid": ["string", "string"]

}

NB. in AoF 0.6 wijkt de URL af van bovenstaande specificaties en dient activatie te worden uitgevoerd op: [base endpointadres van het LSP]/fhir/activate

Op deze interface worden de volgende HTTP headers NIET toegepast: Authorization, AORTA-Transactie, DigiD-Authenticatie.

Toelichting TKID

Middels een activatie van een TKID geeft de GBZ-beheerder aan dat het voor de xIS-instantie, die wordt aangeduid met het applicatieID, een bepaalde set van reeds verkregen acceptaties (nader aangeduid door een set van xIS-type kwalificaties ID's - TKID's) wil activeren. Als gevolg hiervan worden de AORTA systeemrollen, waarvoor het xIS-type blijkens de TKID's is geaccepteerd, in het APR gekoppeld aan de xIS-instantie (de Applicatie). Nadat deze actie is voltooid, kunnen de FHIR capabilities die deel uitmaken van deze AORTA systeemrollen, via de resource broker, bij het xIS worden aangesproken. Bij een activatie wordt een eventueel eerder geregistreerde set van TKID's vervangen door de nieuwe set van TKID's. Indien er een probleem is met één van de TKID's in een set, dan wordt de gehele transactie afgewezen en verandert er dus niets. Het is ook mogelijk om geen enkele tkid te activeren (door geen tkid attribuut op te nemen in de body van het request).

Resource Broker VnC

Verzending & Consolidatie Interface

Generiek

De Verzending & Consolidatie Interface is nagenoeg gelijk aan de AORTA FHIR Resource Interface. Dit geldt zowel voor het generieke deel van de interface als voor de AORTA FHIR * interacties. In deze sectie worden daarom slechts de afwijkingen hierop beschreven.

M.b.t. de HTTP headers die worden gebruikt geldt voor alle interacties de volgende uitzondering:

• Er wordt géén Authorization header gebruikt, maar in plaats daarvan dient het AORTA access_token als volgt worden meegestuurd
  AORTA-Transactie: SAML2-Bearer/JWT-Bearer <transactie_token>
• Tevens zal het, van DigiD ontvangen, authenticatietoken (Assertion), base64url gecodeerd conform RFC 4648) als volgt worden toegevoegd aan ieder request:
  DigiD-Authenticatie: SAML2-Bearer <DigiD SAML Assertion>
• In requests dient de volgende header te worden meegestuurd
  Cache-Control: no-store
• In responses dient de volgende header te worden meegestuurd
  Cache-Control: private

Vooralsnog hoeven slechts JWT-based access_tokens te worden ondersteund.

Doordat de DigiD Assertion wordt verstuurd in een HTTP-header met als naam DigiD-Authenticatie en met een auth_scheme SAML2-Bearer, weet de ontvanger al voor decodering van het token, dat het een op XML-gebaseerde SAMLv2 Assertion betreft, die moet voldoen aan de schema-definitie van DigiD.

{}