Technologie architectuur
Deze pagina beschrijft de technologie architectuur van Koppeltaal GGZ versie 1.3.x maar doet geen uitspraken over de technische manier waarop de deelnemende systemen gerealiseerd moeten worden.
Informatie-uitwisseling op basis van FHIR Messaging
Standaarden
Het transport van berichten volgens Koppeltaal v1.x is gebaseerd op een aantal standaarden: met name HTTP, HL7 FHIR DSTU 1 (v0.0.82) en relevante onderdelen van de HL7 standaard. De content (inhoud) kan zowel in JSON als in XML worden uitgedrukt. Koppeltaal gebruikt HTTP als transportmechanisme om FHIR berichten (resources) uit te kunnen wisselen en Atom feed om FHIR resources te bundelen. De kern van FHIR wordt gevormd door de FHIR DSTU1 resources, waarmee oplossingen voor uitwisseling van zorginhoudelijke gegevens kunnen worden gebouwd. Door middel van profiling (het maken van specificaties in de vorm van structure definitions en extensions) en onderlinge verwijzingen is het mogelijk een specifieke set van FHIR resources voor een bepaalde use case, binnen een domein, te definiëren. Elke applicatie type (eHealth platformen, portalen, interventies of bronsystemen) gebruikt een eigen set van FHIR resources die via een adapter (programmeertaal afhankelijke abstractie laag) met Koppeltaal berichten uitwisselt over het openbare internet.
Netwerktopologie
De netwerktopologie beschrijft de fysieke verbindingen tussen de netwerkcomponenten onderling. Bij Koppeltaal 1.3 wordt een stertopologie toegepast tussen de verschillende GGZ instellingen en Koppeltaal. Dit is de meest gebruikte topologie voor internet. Alle GGZ instellingen (domeinen) worden via internet aangesloten op Koppeltaal. Koppeltaal 1.3 dient hier als technische (centrale) dienstverlener, die voor de eindgebruikers verder niet zichtbaar is. Koppeltaal verwerkt geen data, maar routeert data tussen applicaties, binnen één domein. Het vastleggen van toestemming van de gebruiker is geen Koppeltaal aangelegenheid, maar behoort te liggen bij de organisaties die zich aansluiten.
Het informatiemodel
Het volgende model geeft de verzameling FHIR DSTU1 resources weer die binnen Koppeltaal 1.3 worden gebruikt. De FHIR specificatie definieert een set van datatypes die als FHIR resource elementen gebruikt worden. Het Koppeltaal 1.3 informatiemodel is gebaseerd FHIR Messaging (berichten). Bij FHIR Messaging is men gedwongen om een verzameling van resources (gegevens) op te halen, ongeacht of men daarvan maar een deel van gebruikt.
Alle FHIR resources zijn in de basis generiek en worden met behulp van profielen (profiles) uitgebreid en specifieker gemaakt voor een specifieke toepassing. In een profiel wordt bijvoorbeeld beschreven:
Welke resource elementen worden gebruikt en welke niet en welke additionele elementen (extension) worden toegevoegd die geen onderdeel zijn van de basisspecificatie
Welke terminologieën worden gebruikt in bepaalde elementen
Hoe de resource elementen mappen naar lokale eisen en/of implementaties
Door de manier waarop profiling wordt toegepast binnen FHIR kunnen er voor een bepaalde basis resource verschillende profielen bestaan, bijvoorbeeld afhankelijk van zorgdomein, land, instelling of leverancier. Om interoperabiliteit te borgen is het van belang dat binnen een bepaalde use case dezelfde profielen gebruikt worden.
Voor Koppeltaal 1.3 is een eigen verzameling FHIR resources vastgelegd met hun eigen profile identifiers.
Profile Identifiers
Koppeltaal maakt gebruik van de Other resource extensie van FHIR DSTU1.
Other is ingevoerd om te kunnen omgaan met resource concepten die nog niet zijn gedefinieerd voor FHIR of die buiten het interessegebied van HL7 liggen. De volgende tabel geeft aan welke resource geen onderdeel zijn van FHIR DSTU1, maar wel specifiek als resource binnen Koppeltaal gebruikt wordt.
Other extensions
De Application resource is een representatie van een portaal, interventie of een ander soort aangeboden dienst door Koppeltaal. Een applicatie kan een list van activiteiten aanbieden. In de context van Koppeltaal is een Application resource een profiel van een Device resource.
Alle berichten worden via HTTP operaties uitgewisseld. Op elke verzoekbericht wordt standaard een HTTP-response code teruggegeven. Bij problemen is er soms meer detail informatie vereist, dan alleen de HTTP-response code. Hiervoor wordt dan de OperationOutcome resource gebruikt, waarmee meerdere afzonderlijke problemen kunnen worden geïdentificeerd, die in lijn moeten zijn met de HTTP-response code.
De kern van FHIR Messaging is de MessageHeader resource. Via het event.code- en data element – de berichtgebeurtenis met referentie naar content – worden de verschillende type berichten (interacties) gedefinieerd. De MessageHeader resource is voor Koppeltaal (profiel) uitgebreid met het Patient element, dat een verwijzing is naar een Patient resource die aangeeft bij welk dossier dit bericht behoort. Het MessageHeader.Patient element is echter geen onderdeel van de (core) FHIR MessageHeader.
Interacties
De volgende event.codes (interacties) zijn gedefinieerd om de functionaliteit van Koppeltaal af te dekken, met de daarbij behorende focal FHIR resource die de content van het verzoek bevat, zie het data element.
In de paragraaf "FHIR Resources" is de structuur in detail verder uitgewerkt van alle Koppeltaal resources met alle elementen en attributen.
Uitgangspunten bij informatie-uitwisseling
Informatie uitwisseling gebeurt via FHIR Messaging en operationele uitkomsten.
In FHIR messaging of FHIR-berichten, wordt een bericht verstuurd van een bronapplicatie naar één of meerdere bestemmingen, wanneer er een gebeurtenis plaatsvindt. Het bericht bestaat uit een bundel die wordt geïdentificeerd door het type bericht, waarbij de eerste (FHIR) resource in de bundel een MessageHeader resource is. De MessageHeader heeft een identifier - en een event.code element – de berichtgebeurtenis – die de aard van het bericht uniek identificeert, en het bevat aanvullende verzoek metagegevens. De andere aanvullende (FHIR) resources in de bundel zijn afhankelijk van het type aanvraag. Het data element heeft een referentie naar de onderliggende resource (de focal resource), waar dit berichttype toe behoort.
MessageHeader van CreateOrUpdateCarePlan
Operationele uitkomsten zijn een verzameling van fout-, waarschuwings- en informatieberichten die gedetailleerde informatie geven over het resultaat van een bepaalde gebeurtenis. Het bericht, een OperationOutcome resource, wordt geleverd als een directe systeem response, of als onderdeel daarvan, waar ze informatie geven over het resultaat van een bepaalde gebeurtenis.
Berichten zijn self-contained
Elk bericht dat tussen applicaties wordt uitgewisseld moet op zichzelf staan (self-contained), er wordt niet verwezen naar externe bronnen. De reden van dit uitgangspunt is dat nieuwe aangesloten applicaties altijd up-to-date zijn met de gegevensuitwisseling en dat er geen kopieën van gegevens opgeslagen worden. Alle gegevens waarvan de verzendende applicatie eigenaar van is, moeten in de berichtenbundel opgenomen worden.
Gegevens waarvan de verzendende applicatie geen eigenaar van is, krijgen een verwijzing in de bundel mee via een URL. Een voorbeeld hiervan is van een geselecteerde ActivityDefinition met een identifier in een CreateOrUpdateCarePlan-bericht.
Referentie vanuit CarePlan naar ActivityDefinition
FHIR resources zijn uniek identificeerbaar
Alle berichten en de daarin voorkomende resource moeten uniek binnen een domein identificeerbaar zijn. Hiervoor wordt het "id" element of attribuut gebruikt. Het "id" wordt door een lokale (interne) dienst uitgegeven en gebruikt tussen applicaties binnen een domein. Als gegevens worden gekopieerd, wijzigt het "id", omdat het "id" als interne sleutel wordt gebruikt om gegevens, zoals berichten, uniek te kunnen identificeren bij één dienst.
In de context van de gezondheidszorg worden de (FHIR) resources geïdentificeerd aan de hand van veelgebruikte type identficaties voor personen, organisaties, definities, etc. Deze (FHIR) resources worden in bronsystemen vastgelegd, waarin overdraagbare identificaties zijn toegewezen om zo de resources buiten de context van Koppeltaal te kunnen identificeren, te gebruiken en te volgen. Hiervoor wordt het element "identifier" gebruikt.
id versus identifier
De volgende tabel toont welke type "identifiers" er gebruikt worden in de verschillende Koppeltaal berichten.
Berichten worden via een standaard HTTP operaties uitgewisseld
Operaties zijn bewerkingen die op FHIR resources uitgevoerd kunnen worden. Hierdoor kunnen applicaties met elkaar communiceren. FHIR suggereert het gebruik van standaard HTTP-werkwoorden (GET, POST, PUT en DELETE) als operaties. Dit resulteert in een generieke, voor zichzelf sprekende interface op basis van welke applicaties interactie hebben met andere applicaties (via Koppeltaal).
URL opbouw
Voor internet is er een uniek concept voor id’s: de URL of Uniform Resource Locator. De URL geeft de unieke locatie van een bron aan.
Aan elke resource (gegevensbron) wordt een unieke FHIR-basis URL toegewezen, welke de basis vormt als referentie naar de resource. Elke resource dat in een FHIR message (bericht) wordt gestopt, moet een unieke URL hebben die er als volgt uitziet:
scheme://FHIR Basis URL + "/" + Resource Type + "/" + id [ + "/_history/" + Versie Id]
Als de resource nog niet aangemaakt is, is er nog geen historie. Voorbeeld:
POST https://vzvz.nl/fhir/Koppeltaal/**Other**/ActivityDefinition:6720
URL opbouw.
URL’s moeten voldoen aan RFC3986 sectie 6 appendix A.
Berichten hebben meerdere representaties
Een representatie van een bericht is een indeling waarin de gegevens (FHIR resources) worden getransporteerd tussen applicaties. Door gebruik te maken van HTTP content negotiatie (onderhandeling over inhoud) kan een aanvrager (client) vragen om een representatie in een bepaald formaat. FHIR staat meerdere representaties toe. De aanvragers (clients) kunnen worden opgebouwd rond XML en JSON.
XML- content
JSON- content
Resource content hebben een versie id
Bij het aanmaken of wijzigen van resources, houdt de Koppeltaal server de resource content en versie id van de resource bij, en deelt bij nieuwe of bij wijzigingen van de resource content, een nieuwe versie id uit, dat een datetimestamp in UTC is. De aanvrager (client) mag de versie id nooit wijzigen.
Om wijzigingen op gegevens gecontroleerd uit te voeren, wordt er gebruik gemaakt van "Optimistic Locking" omdat het HTTP protocol "stateless" is. De Koppeltaal server onthoudt geen locks.
Bij het wijzigen van de resource content moet de aanvrager (client) de meest recente versie id van de resource meesturen. Indien de versie id van de aanvrager niet match met de versie id van wat de Koppeltaal server als laatst heeft uitgegeven, wordt het wijzigingsverzoek van de aanvrager niet geaccepteerd en krijgt de aanvrager een HTTP status code "409: Conflict" antwoord terug, met gedetailleerde informatie in een "OperationOutcome" resource over welke resource(s) de verkeerde versie id gebruiken.
Versie id foutmelding met Patient 382.
In antwoord op aanvragen wordt in het MessageHeader.data element gerefereerd naar de focal resource van het bericht, oftewel de root van het bericht. Deze referentie is alleen bij een wijziging op een bestaande resource geversioneerd.
Referentie naar geversioneerde CarePlan 1234
De 'Conformance Statement'
Conformance is het voldoen aan (interne) kwaliteitsdoelstellingen en het invullen en naleven van intern beleid, mede door gebruik van externe standaarden (zoals OAuth2). Een 'Conformance Statement' (conformiteitsverklaring) is een belangrijk onderdeel van FHIR. Het wordt gebruikt als een verklaring van kenmerken van de daadwerkelijke serverfunctionaliteit of van een verzameling regels waaraan een toepassing moet voldoen.
Bij informatie uitwisseling via FHIR Messaging hebben we ook te maken met (eenmalige) authenticatie van de participanten door gebruik te maken van Single Sign-On (SSO) bij het lanceren van interventies (eHealth modules). Hierbij moeten participanten zich eenmalig authentiseren, waarna ze automatisch toegang krijgen tot meerdere applicaties en resources in een domein van Koppeltaal. Met behulp van het 'Conformance Statement' kunnen aangesloten applicaties informatie over de OAuth2 implementatie bij Koppeltaal voor Single-Sign-On achterhalen.
Het opvragen van het 'Conformance Statement' met betrekking to OAuth2 URL’s bij Koppeltaal wordt verkregen via de GET operatie naar een vast endpoint (URL), bijvoorbeeld GET https://base.koppeltaal.nl/fhir/Koppeltaal**/metadata**. Hiermee krijgt de aanvrager informatie over de OAuth2 implementatie voor Single-Sign-On. De 'Conformance Statement' resource is hiervoor uitgebreid met launch (opstart) URL’s.
Conformance Statement
Volgende tabel geeft een overzicht van de nieuwe URL’s die door Koppeltaal wordt gebruik voor OAuth2.
Daarnaast definieert Koppeltaal 4 extensies die de validatie van verzoeken (request) en antwoorden (reply) regelen:
Algemene informatie over de 'Conformance Statement' kan men vinden bij https://www.hl7.org/fhir/DSTU1/conformance.html.
Het applicatie model
Koppeltaal ondersteunt alleen de voor gedefinieerde interacties en binnen deze sectie wordt gekeken naar deze interacties tussen de verschillende type applicaties binnen een domein.
Er zijn verschillende typen applicaties betrokken ter ondersteuning van een interactief zorgproces. Functioneel zijn alle applicaties onderdeel van de gehele Koppeltaal omgeving en ondersteunen het interactieproces vanuit verschillende rollen voor de gebruikers. Per domein sluit een applicatie aan met een unieke applicatie-instantie, waarin die rollen binnen dat domein zijn gedefinieerd.
We onderscheiden de volgende (technische) rollen binnen Koppeltaal:
Voor de verschillende type Portalen (toegangspoort voor participanten) onderscheiden we de Patient, Practitioner en RelatedPerson
Voor de verschillende type interventies onderscheiden we de Game, E-Learning en ROM
Applicaties kunnen in andere applicaties geïntegreerd zijn, als onderdeel van een behandelplan.
Indien de applicatie als rol een Interventie type representeert kan deze verschillende 'ActivityDefinitions' publiceren bij Koppeltaal. Deze 'ActivityDefinitions' kunnen vervolgens via Koppeltaal in een Portaal aan een participant getoond worden.
Applicaties met een unieke applicatie-instantie, waarin die rollen binnen dat domein zijn gedefinieerd, mogen alleen binnen dat domein met elkaar communiceren.
Koppeltaal ondersteunt de volgende processen voor de uitwisseling van berichten:
Bericht versturen
Bericht routeren
Bericht notificatie
Bericht ophalen
Bericht versturen
Alle applicaties maken gebruik van de standaard HTTP operatie POST om berichten (FHIR Message DSTU1) te versturen. De berichten worden naar een vaste endpoint (URL) van Koppeltaal gestuurd, zie 'interactie ontvangen' (technische service) waarvan de basis URL bijvoorbeeld <KoppeltaalOmgevingURL>/FHIR/Koppeltaal/Mailbox is. Elk binnenkomend bericht wordt (tijdelijk) gepersisteerd in een datastore. De structuur van het bericht is, in hoofdstuk "Informatie-uitwisseling op basis van FHIR Messaging", beschreven.
De opslag van de Message Header (metadata van het bericht) en de content van het bericht (Message Body) zullen apart gepersisteerd worden in verschillende tabellen.
Elk bericht dat gestuurd wordt door een applicaties, heeft een versie id als het om een wijziging gaat van gegevens (focal resources). Elke applicatie dat een nieuwe (resource) bericht publiceert of aanpast moet een subscriptie (abonnement) voor deze interactie nemen, om de versie id van zijn eigen interne resource ‘up-to-date’ te houden met dat van anderen. Elk bericht dat door een applicatie verstuurd wordt, moet de laatste versie id gebruiken, dat door Koppeltaal wordt uitgegeven. Koppeltaal zal van elk binnenkomend bericht de versie id controleren met wat Koppeltaal zelf heeft uitgegeven, en het bericht pas accepteren als de versie id’s van de focal resources gelijk zijn.
In Koppeltaal worden de subscripties (abonnementen) per type bericht, per geregistreerde applicatie binnen een domein aangemaakt en beheerd.
Bericht routeren
Het routeren van binnenkomende berichten gebeurt binnen een domein en de berichten worden aan die applicaties opgeleverd waar een subscriptie (gekoppeld abonnement) in Koppeltaal voor is. De subscripties zijn deel van de unieke applicatie-instantie configuratie en zijn gespecificeerd per type bericht die door Koppeltaal worden ondersteund, zie "Interacties".
Bericht notificatie
Koppeltaal biedt een functie aan om notificaties te versturen als er een nieuw bericht beschikbaar is voor een applicatie. Deze notificatie is geïmplementeerd middels REST WebHooks. Om een notificatie te kunnen ontvangen zijn de volgende configuratie acties nodig:
Een WebHook URL definiëren, tijdens de registratie en configuratie van een applicatie in het domein, die Koppeltaal kan aanroepen.
De lokale implementatie achter de WebHook URL is nodig om notificaties te kunnen interpreteren. Koppeltaal zal een event genereren, ter informatie dat er ‘nieuwe’ berichten beschikbaar zijn. Het event, een notificatie bericht, bevat geen payload.
De betreffende applicatie wordt maximaal 5 keer gesignaleerd. De applicatie kan daarna het bericht lezen zoals al beschreven in paragraaf Bericht ophalen.
Een notificatie bericht in Koppeltaal maakt gebruik van de volgende HTTP headers:
Category. Bevat de domein headers. Bijvoorbeeld:Category: http://ggz.koppeltaal.nl/fhir/Koppeltaal/Domain#{Domain}; scheme=""; label="http://hl7.org/fhir/tag/security{Domain}". Dit header veld is vanaf Koppeltaal 1.3.8 ingevoerd.KoppeltaalMessageIdentifier. Hiermee wordt een correlatie id (MessageHeader.identifier) meegestuurd van het bericht dat beschikbaar is voor de applicatie. Vanaf Koppeltaal 1.3.8 ingevoerd.Content-TypeenAccept. Worden altijd gevuld met "application/json". Gebaseerd op RFC-7231. Vanaf Koppeltaal 1.3.8 ingevoerd.X-Koppeltaal-Secret. Is een voorbeeld van een custom header, die kunnen worden geconfigureerd per 'application instance'. Bijvoorbeeld met een secret value dat gedeeld wordt tussen applicaties (KT domain en platform).Content-Length. Geeft de grootte van de payload aan. Deze parameter wordt run-time bepaald en is voor notificatie berichten altijd 0.
Bericht ophalen
Alle applicaties maken gebruik van de standaard HTTP operatie GET om berichten (FHIR Message DSTU1) op te halen. De berichten kunnen van een vaste endpoint (URL) bij Koppeltaal opgehaald worden, zie 'interactie ophalen' (technische service) waarvan de basis URL bijvoorbeeld <KoppeltaalOmgevingURL>/FHIR/Koppeltaal/MessageHeader is.
Indien een applicatie niet gebruik maakt van notificaties en de REST WebHooks niet geïmplementeerd heeft, kan de applicatie de Koppeltaal server met een vaste interval bevragen (actief polling). De frequentie waarmee deze opvragen plaatsvindt, heet de poll frequentie.
Aan de hand van de basis URL en MessageHeader.id kan men één geïdentificeerd bericht ophalen. Met behulp van de basis URL, _search operatie en _query parameters kan men een bundel MessageHeaders opvragen en hiermee vervolgens de bundel doorzoeken naar de juiste MessageHeader.id met onderliggende content.
De volgende _search operatie en _query parameters worden door Koppeltaal 1.3 ondersteund.
GET https://koppeltaal.nl/FHIR/Koppeltaal/MessageHeader/_search?_query=MessageHeader.GetNextNewAndClaim- zoeken naar een volgend bericht met ProcessingStatus= "New", maak ProcessingStatus "Claimed", en stuur dat specifieke bericht terug. Deze call zal altijd het gevolg moeten zijn van een update van de Message status. Deze interactie heeft tot gevolg dat de berichtstatus wordt aangepast.GET https://koppeltaal.nl/FHIR/Koppeltaal/MessageHeader/_search?_count=[X\]- deze stuurt een Bundle van MessageHeaders terug om de applicaties te laten zoeken naar een of meerdere specifieke berichten. Een pagesize kan doorgegeven worden met de _count parameter, met een max van 1000.GET https://koppeltaal.nl/FHIR/Koppeltaal/MessageHeader/_search?_id=[id\]- deze kan gebruikt worden om een complete Bundle voor een specifiek bericht te krijgen (bijv. Als de MessageHeader bekend was door de voorgaande zoekactie)
De volgende additionele _query parameters kunnen gespecificeerd worden:
Patient: Filtert op de patiënt dossier waar het bericht aan gerelateerd is.
Event: Filtert op het bericht type
ProcessingStatus: Filtert op de ProcessingStatus. (New|Claimed|Success|Failed). Deze query parameter kan geen onderdeel zijn van de named query van interactie 1, zoals hierboven beschreven.
Voor het ophalen en verwerken van de MessageHeaders is er een specifiek Koppeltaal element ‘ProcessingStatus’ toegevoegd, die aangeeft wat de stand is van de verwerking van een bericht. Dit element is geen standaard element van de MessageHeader resource.
Het 'ProcessingStatus' element heeft één van de 6 mogelijke verwerkingstoestanden. Namelijk:
NEW. Dit bericht is nog niet opgehaald en gelezen door de betreffende applicatie
CLAIMED. Dit bericht is door een applicatie geclaimd. Dit is een tijdelijke toestand, want als het bericht volledig gelezen is dan is er SUCCES geboekt. Een CLAIM kan ook vervallen, bij een time-out wordt de toestand van het bericht weer op NEW gezet.
SUCCESS. Het bericht is succesvol opgehaald en gelezen door de betreffende applicaties.
ARCHIVED. Ongelezen nieuwe berichten of berichten die succesvol waren gelezen, waarvan bewaartermijn van verlopen is.
FAILED. Berichten die een structurele fout hebben.
MAXIMUMRETRIESEXCEEDED. Na maximum (van 5) keer geprobeerd te hebben om het bericht op te halen.
Het SMART App launch raamwerk
Naast het kunnen uitwisselen van gegevens ondersteunt Koppeltaal ook het koppelen van applicaties van derden met deze gegevens, waardoor apps kunnen worden gestart binnen de gebruikersinterface of context van Koppeltaal. SMART staat voor "Substitutable Medical Applications and Resuable Technologies". Dit raamwerk ondersteunt apps voor gebruik van behandelaren, patiënten en anderen via een Portal of een FHIR systeem waar een gebruiker toestemming kan geven om een app te starten. Het raamwerk biedt een betrouwbaar, veilig autorisatie protocol voor verschillende app-architecturen, waaronder apps die op een beveiligd platform draaien en op het apparaat van een eindgebruiker draaien.
Het SMART App launch raamwerk definieert een methode waarmee een app (eenmalig) toestemming vraagt om toegang te krijgen tot een FHIR-resource en die autorisatie (toegangstoken) vervolgens gebruikt om de resource op te halen. Het SMART App launch raamwerk bij Koppeltaal is gebaseerd op de OAuth2 standaard (RFC6749 en RFC6750) en geïmplementeerd volgens de SMART-on-FHIR voorschriften (zie http://www.hl7.org/fhir/smart-app-launch/1.0.0).
Volgens de OAuth2 specificaties kunnen er twee typen Clients worden onderscheiden:
"Public Client" Een Public Client draait volledig op een eindgebruiker apparaat. Gevolg is dat de applicatie geen "cliënt secret" kan beschermen in het geval dat er ook geen applicatie logica op een server zou draaien. Voorbeelden JavaScript app in een browser. The Ranj Kick-ASS game is een voorbeeld van een Public Client applicatie.
"Confidential Client" Is een applicatie die een "cliënt secret" kan beschermen door gebruik te maken van “server-side business logic”. Het grote verschil tussen Publieke en Confidentiële Clients is als de Client de toegang tot het Token endpoint gebruikt, de confidentiële Client de client_id en client_secret als basis authenticatie header kan aanleveren.
Toegangstokens worden aangevraagd bij een OAuth2-compatibele autorisatieserver (Koppeltaal server) via een TLS beveiligde kanaal (zie hoofdstuk "Beveiliging").
Configuratie gegevens, zoals codes en toegangstokens, kan men via de Conformance Statement (zie paragraaf De 'Conformance Statement' ) opvragen.
De mate waarin informatie en gegevens (resources) beschermt moet worden zodat (eind)gebruikers, en andere producten de juiste mate van gegevenstoegang hebben passend bij hun soort en niveau van autorisatie.
Elke applicatie is verantwoordelijk voor het beschermen van zichzelf tegen mogelijke wangedrag of kwaadaardige waarden voor het verkrijgen van ongeoorloofde toegang en gebruik. Elke applicatie moet daarvoor de nodige tegenmaatregelen nemen om zichzelf en alle gevoelige informatie die deze bevat, te beschermen. Zie hiervoor de "OAuth 2.0 Threat Model and Security Considerations" (RFC6819).
Naast het borgen van kwaliteitscriteria vereist de norm NEN 7510 dat informatiebeveiligingsmaatregelen op controleerbare wijze zijn ingericht voordat kan worden gesproken over adequate informatiebeveiliging.
Authenticatie
Authenticatie wordt bij Koppeltaal op applicatie-instantie niveau afgehandeld. Dat wil zeggen dat een (applicatie) account wordt aangemaakt voor een applicatie-instantie en deze wordt vervolgens aan een domein gekoppeld. Een applicatie account heeft een unieke gebruikersnaam en wachtwoord.
De gebruikersnaam en wachtwoord, die toegekend zijn aan een applicatie-instantie, worden in de koptekst (header) van HTTP op de volgende manier geplaatst: 'Authorization : Basic <credentials>', waarbij de credentials een Base64 codering is van gebruikersnaam en wachtwoord, verbonden met een dubbele punt ':'. Dit wordt in RFC7617 2015 gespecificeerd.
Er kan ook gebruik gemaakt worden van een OAuth2 bearer token voor authenticatie, die door een applicatie-instantie verkregen wordt, via een handshake protocol met Koppeltaal. De applicatie-instantie plaatst het token op de volgende manier in de koptekst (header) van HTTP: 'Authorization : Bearer <token>'. Het token is een Base64 codering.
Alle interacties worden onder een applicatie account uitgevoerd (en bevinden zich daardoor binnen een domein).
Na succesvolle authenticatie wordt geverifieerd dat het domein dat in het bericht is opgegeven, hetzelfde domein is als waaraan de geverifieerde gebruiker is toegewezen.
De Single-Sign-On (SSO) flow
Bij Koppeltaal maken we gebruik van Single-Sign-On (SSO). Hiermee kunnen eindgebruikers zich eenmalig authentiseren (inlog procedure), waarna automatisch toegang wordt verschaft tot meerdere type applicaties en resources in het Koppeltaal domein.
Koppeltaal ondersteunt twee typen van Single-Sign-On flows, met Koppeltaal Server als OAuth2-compatibele autorisatieserver en de Applicatie als OAuth2 Client:
SMART Autorisatie voor webapplicaties, voor het autoriseren en starten van webapplicaties (zoals een eHealth-module, of een ROM lijst).
SMART Autorisatie voor mobiele apps, voor het starten van een app op een smartphone van een eindgebruiker.
Koppeltaal biedt na het authenticatie proces en na selectie van activiteiten via het Portal de gebruiker een URL link aan naar een applicatie (interventie), waarmee de gebruiker de applicatie kan starten. De gebruiker heeft hiermee zowel het Portal als een (web of mobiele) applicatie tot zijn beschikking.
Wanneer de gebruiker de applicatie URL opent, moeten de volgende gegevens aan Koppeltaal doorgegeven worden:
Application Identifier (gekoppeld aan een specifieke applicatie) – noodzakelijk om de Koppeltaalserver de publicerende applicatie en zijn URL op te kunnen zoeken.
Patient identifier – wordt gebruikt om de patiënt te identificeren door de applicatie (Game).
User identifier – wordt gebruikt door de applicatie om correcte views te laten zien voor die gebruiker
Een overeengekomen security token van de applicatie naar de Koppeltaal Server wordt verstuurd, zodat de Koppeltaal server kan verifiëren dat de aanroepende applicatie een bekende (en geregistreerde) applicatie is die kan worden vertrouwd in de context van domein en applicatie-instantie. Dit token bevat tenminste een Hash van de URL van de applicatie en voorkomt dat iemand de URL van de applicatie (het adres) aanpast en opnieuw indient bij de Koppeltaal Server. Tevens bevat het token een (geheime) code die zowel bij de applicatie als de Koppeltaal server bekend is en, mogelijk, een Nonce die voorkomt dat de URL meerder malen (sessies, resource) misbruikt kan worden.
Naast de bovengenoemde velden, kunnen er ook optionele velden gebruikt worden die doorgegeven worden:
CarePlanActivity identifier – gebruikt om te achterhalen welke activiteiten een bepaalde applicatie (Game) herkent.
Aanvullende applicatie informatie - bijvoorbeeld dat er een specifieke pagina door de applicatie moet worden geopend.
In de huidige Koppeltaal 1.3.x is het niet verplicht om een activity id mee te sturen, maar is het wel wenselijk. We gedogen dit alleen om de mogelijkheid te scheppen om de SSO tussen twee systemen op te kunnen zetten, waarvoor geen activity id nodig is.
SMART Autorisatie voor webapplicaties
Met behulp van de 'Conformance Statement' (zie paragraaf De 'Conformance Statement') kan een (gelanceerde) applicatie een OAuth2 autorisatie verzoek indienen bij Koppeltaal (zie ook RFC 6749). De applicatie gebruikt hierbij de authorize- en token endpoints uit de 'Conformance Statement'. De applicatie moet de scoop van het autorisatie verzoek specificeren, dit is onderdeel van het OAuth2 protocol, dat voor Koppeltaal v1.3 "patient/*.*" is. Dit betekent dat de applicatie toegang vraagt tot alle berichten van de patiënt waarop deze applicatie is geabonneerd. Verder worden bij het autorisatie verzoek de volgende parameters doorgegeven aan Koppeltaal:
reponse_type. Dit wordt ingevuld met de waarde 'code' waarmee de aanvragende applicatie aangeeft dat het een autorisatie code wil ontvangen.
client_id. Moet worden ingevuld met de waarde van de toegewezen identifier van de aanroepende applicatie
scope. Bevat de scopes "patient/*,read" en "launch:applicatie-instantie", om de verbinding te leggen tussen de vragende context en lanceer aanvraag
redirect_uri. Is de URL waarheen de aanvragende applicatie wordt gerouteerd, na een succesvolle autorisatie bij Koppeltaal
state. Een optionele toestandswaarde dat de gelanceerde applicatie kan gebruiken voor het kunnen traceren van de aanvraag
SMART autorisatie verzoek
Voor het autorisatie verzoek zal Koppeltaal een authorization_code via de redirect_uri teruggeven als de autorisatie aanvrager toegang krijgt. Indien het verzoek wordt afgewezen, krijgt de autorisatie aanvrager een foutmelding. Verder wordt de state van het autorisatie verzoek meegestuurd in het antwoord.
Antwoord op autorisatie verzoek
Autorisatiecodes zijn van korte duur en verlopen meestal binnen een minuut.
De laatste stap die de app vervolgens moet uitvoeren, is de autorisatie code omwisselen voor een toegangstoken (Zie ook RFC6749 sectie 4.1.3). Hiervoor gebruikt de applicatie het token endpoint uit de ‘Conformance Statement’. De volgende parameters worden aan Koppeltaal doorgegeven voor de uitwisseling:
grant_type. Vaste waarde : "authorization_code"
code. De code die bij het autorisatie verzoek is ontvangen
redirect_uri. Is de URL waarheen de aanvragende applicatie wordt gerouteerd, na een succesvolle uitwisseling bij Koppeltaal
client_id. Moet worden ingevuld met de waarde van de toegewezen identifier van de aanroepende applicatie
Koppeltaal geeft de volgende informatie terug bij uitwisseling.
access_token. Het toegangstoken dat de applicatie gebruikt voor het opvragen van gegevens (het formaat van het token is in RFC6749 en RFC7650 beschreven)
toke_type. Is een vaste waarde "Bearer"
expires_in. De levensduur in seconden van de afgegeven toegangstoken (RFC6749 section 1.5)
scope. De scope waarop autorisatie is gegeven
id_token. Identificeert de patiënt en user details, als hierom gevraagd wordt
refresh_token (optioneel). Token dat gebruikt kan worden om een nieuw toegangstoken te verkrijgen.
Toegangstoken opvragen
Toegangstoken antwoord
Een groot aantal bedreigingen die men ondervindt bij toegangstokens kan men beperken door het token digitaal te ondertekenen, zoals gespecificeerd in RFC7515 of door in plaats daarvan een Message Authentication Code (MAC) te gebruiken. Het digitaal ondertekenen van een toegangstoken is in Koppeltaal 1.3 niet gespecificeerd.
SMART Autorisatie voor mobiele apps
SMART Autorisatie voor mobiele apps lijkt vrij veel op de webapplicatie autorisatie zoals hiervoor is aangegeven, met kleine verschillen:
Het eerste verzoek wordt gedaan aan een speciale MobileLaunch Endpoint. Hier zal een mobile activatie code aangevraagd worden. Dit verzoek wordt gedaan (zoals elke Koppeltaal call) onder de credentials van de applicatie-instantie.
Een Mobile Launch Activatie code opvragen met alle benodigde parameters (zoals bij de webapplicatie autorisatie beschreven):
Mobiele Launch Activate code opvragen
Het antwoord is een activatie code en houdbaarheidsduur in dagen
Deze activatie code zal vervolgens aan de gebruiker doorgegeven moeten worden, die gebruik wil maken van de mobiele app en deze code kan slechts één keer gebruikt worden.
Wanneer de mobiele opgestart wordt, wordt de gebruiker gevraagd om de activeringscode (activation_code) in te voeren. De mobiele app moet een hard gecodeerde of configureerbare FHIR-basis URL hebben van Koppeltaal waarheen hij vervolgens een autorisatie verzoek kan heen sturen. De FHIR-basis URL komt initieel niet mee, bij het opstarten van de mobiele app.
Vervolgens moet de mobiele app, de authorize- en token endpoints via het 'Conformance Statement' bij Koppeltaal ophalen, zoals bij de 'SMART Autorisatie voor webapplicaties' is beschreven.
Koppeltaal retourneert op een autorisatie verzoek een JSON antwoord:
Met deze authorisation_code kan men weer vervolgens een toegangstoken opvragen, zoals ook beschreven is in de 'SMART Autorisatie voor webapplicaties'.
Gebruik van de Refresh token
Voor een specifieke ClientId kan de Koppeltaal Server geconfigureerd worden om een refresh_token bij te voegen binnen de Token Request.
Voorbeeld van de Token:
Toegang- met refresh token
De expiratie tijd gespecificeerd door de "expires_in" is 15 minuten of korter, met de indicatie dat de access_token gauw niet meer geldig zal zijn. Koppeltaal gebruikt de code 'expired' als OperationOutcome als een verzoek niet gelukt is vanwege een timeout.
Berichtenstructuur
Het transport van berichten volgens Koppeltaal v1.x is gebaseerd op een aantal standaarden: met name HTTP, HL7 FHIR DSTU 1 (v0.0.82) en relevante onderdelen van de HL7 standaard. De content (inhoud) kan zowel in JSON als in XML worden uitgedrukt. Koppeltaal gebruikt HTTP als transportmechanisme om FHIR berichten (resources) uit te kunnen wisselen en Atom feed om FHIR resources te bundelen. Zie onderstaand figuur.
FHIR Messaging
De (huidige) uitwisselingsmethoden van Koppeltaal is gebaseerd op basis van messages (qua methodiek vergelijkbaar met HL7V2 messaging). Deze standaard wordt gezien als voldoende stabiel als basis voor implementaties voor Koppeltaal 1.3. Elke FHIR message bestaat uit een FHIR MessageHeader element en uit een lijst van resources (vergelijkbaar met HL7V2 message segmenten) die gebaseerd zijn op FHIR DSTU1 (Draft Standard for Trial Use) en gedefinieerd worden in de MessageHeader. De verschillende messages realiseren de functionaliteit van Koppeltaal.
In de volgende tabel staat welke FHIR resource entries minimaal aanwezig moeten zijn bij de voor gedefinieerde Koppeltaal bericht types (MessageHeader.event.code: codering die het event identificeert wat het bericht betekent). Indien er naar een FHIR resource wordt gerefereerd, dient deze volledig aanwezig te zijn zoals deze onder hoofdstuk "FHIR Resources" in volgende paragrafen beschreven wordt.
FHIR Messagetypes
[1] De Event.code is een element van de MessageHeader en identificeert het berichttype (of interactie).
FHIR Resources
Data Types
De FHIR resource elementen worden gespecificeerd aan de hand van een set data types. Er zijn twee categorieën data types: de eenvoudige en primitieve types, geïmporteerd uit de XML Schema (https://www.w3.org/TR/xmlschema-2) en complexe types, die herbruikbare clusters van elementen zijn.
De set data types die in de FHIR resources elementen uit de Technologie architectuur worden gebruikt, vindt men in FHIR DSTU 1 Data Types terug.
FHIR Bundle (Atom Feeds)
Een veelvoorkomende bewerking die met FHIR resources wordt uitgevoerd, is het verzamelen van FHIR resources in één instantie (bericht). In FHIR wordt dit bundelen genoemd, Dit bundelen bevat niet alleen verwijzingen naar FHIR resources maar ook de volledige inhoud van de FHIR resources
Bij het bundelen van FHIR DSTU1 resources, wordt gebruik gemaakt van het feed Atom-formaat, zie [RFC4287] en https://www.hl7.org/fhir/DSTU1/xml.html#atom. Koppeltaal v1.x gebruikt het Atom-formaat als basis om de gegevens (FHIR resources) d.m.v. berichttypes te bundelen.
De definitie van de bundel bestaat uit een feed element, dat een willekeurig aantal invoer elementen bevat. De feed is als volgt opgebouwd:
Tabel 2. FHIR Bundle (Atom feed) De verschillende onderdelen van de FHIR feed in Koppeltaal v1.3 ziet er als volgt uit:
FHIR Bundle (Atom feed)
MessageHeader
MessageHeader
Volgende plaatje laat zien dat de MessageHeader resource is uitgebreid met het Patient element dat een verwijzing is naar een Patient resource die aangeeft bij welk dossier dit bericht behoort. Het MessageHeader.Patient element is geen onderdeel van de (core) FHIR MessageHeader. Het data element heeft een referentie naar de onderliggende resource waar dit berichttype toe behoort.
ActivityDefinition (Other)
ActivityDefinition (Other)
CarePlan
CarePlan
CareTeam (Other)
Het CareTeam wordt opgenomen in het CreateOrUpdateCarePlan bericht als resource entry als er in het bericht verwezen wordt naar het CareTeam.
In de definitiebepaling van het CareTeam is zo veel mogelijk gebruik gemaakt van de FHIR STU3 CareTeam definitie zodat bij een overgang naar FHIR STU3 en de compatibiliteit van DSTU1 naar STU3 hierin zo min mogelijk verschil is.
CareTeam (Other)
CarePlanActivityStatus (Other)
CarePlanActivityStatus (Other)
Deprecated CarePlanActivityResult (Other)
De FHIR resource "CarePlanActivityResult" is niet in Koppeltaal 1.3.x geïmplementeerd door Koppeltaal leveranciers, en wordt door de Koppeltaal architectuur afgeraden om deze in te zetten om de resultaten van een activiteit op te vragen.
CarePlanActivityResult (Other)
Organization
Organization
Patient
Patient
Practitioner
Practitioner
RelatedPerson
RelatedPerson
Application (Device profile)
Application
UserMessage (Other)
UserMessage
Identifiers
In de context van de gezondheidszorg worden een aantal veelgebruikte type identficaties voor zowel organisaties, zorginstanties als personen gebruikt. De volgende paragrafen tonen welke type identifiers er gebruikt worden in de verschillende Koppeltaal berichten.
Merk op dat het niet is toegestaan om ‘placeholder’ identificaties te gebruiken, zoals ‘UNKNOWN’, ‘NULL’ of 9999. Als een identificatie in een bericht wordt gebruikt, moet dit een unieke identifier zijn voor de entiteit binnen het gegeven systeem. Met andere woorden er mogen nooit twee entiteiten van hetzelfde type zijn die exact dezelfde identificatie hebben.
Common identifiers
Onderstaande identificatie systemen worden veel gebruikt in de gezondsheidszorg in Nederland. Om het gebruik ervan zoveel mogelijk te standaardiseren gebruikt men onderstaande informatie waar één van de identificatie gegevens wordt gebruikt.
Common Identifiers
Notitie: De System Uri’s vindt men bij [http://fhir.nl/fhir/NamingSystems/[SystemUri](http://fhir.nl/fhir/NamingSystems/%5bSystemUri)\\]
Value Sets
CarePlanActivityResultStatus
MessageEvents
ApplicationRoles
DeviceKind
ActivityKind
MessageKind
CarePlanActivityStatus
OtherResourceUsage
QuestionnaireStatus
CarePlanParticipantRole
ProcessingStatus
ActivityPerformer
ActivityDefinitionLaunchType
CarePlanRelationTypes
CareTeamStatus
Beveiliging
De communicatie en gegevensuitwisseling tussen de Koppeltaal Server en de applicaties uit een domein volgen de ICT-beveiligingsrichtlijnen voor Transport Layer Security (TLS) v2.0 van het Nationaal Cyber Security Centrum (NCSC). Versie 2.0 is op 23 april 2019 gepubliceerd.
VZVZ vereist dat de veiligheidsniveau (zoals beschreven in de ICT-beveiligingsrichtlijnen) voor het Transport Layer Security-protocol (TLS) minimaal moeten voldoen aan: "Voldoende of hoger". TLS is het gebruikte protocol voor het opzetten en gebruiken van een cryptografisch beveiligde verbinding tussen twee computersystemen, een cliënt en een server.
Organisaties die gebruik maken van een ‘uit te faseren’ TLS-configuratie moeten deze configuratie op termijn vervangen. Anders lopen organisaties het risico dat zij niet voldoen aan de beveiligingseisen die volgen uit de AVG.
Verder volgt VZVZ de ICT-beveiligingsrichtlijnen voor Webapplicaties, om een bepaalde mate van veiligheid voor Koppeltaal te bereiken. Deze richtlijnen hebben niet alleen betrekking op webapplicaties, maar ook op de beheeromgeving en de omringende hard- en softwareomgeving die noodzakelijk is om webapplicaties te laten functioneren.
Het NCSC is verantwoordelijk voor het opstellen en onderhouden van bovenstaande richtlijnen en zal ze periodiek actualiseren. Indien noodzakelijk zal het NCSC tussentijds door middel van een addendum of erratum de richtlijnen aanpassen. Daarnaast wordt in beveiligingsrichtlijnen verwezen naar andere relevante normen of standaarden zoals de Open Web Application Security Project (OWASP) Top 10 Web Applicaties beveiligingsrisico's.
Autorisatie beheer
Koppeltaal Support beheert verschillende diensten, zoals het beheer van de domeinen, applicaties, applicatie-instanties, SSO links, etc. Voor deze diensten zijn er rollen gedefinieerd, waaraan bepaalde rechten worden toegekend. Volgende matrix geeft per rol de overzicht van toegekende rechten weer.
Tabel 16 Autorisatie beheer matrix.
Last updated
