Koppeltaal 2.0 Implementation Guide (Full Documentation)
0.16.2 - ci-build
NL
Koppeltaal 2.0 Implementation Guide (Full Documentation)
0.16.2 - ci-build
NL
Koppeltaal 2.0 Implementation Guide (Full Documentation) - Local Development build (v0.16.2) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions
| Page standards status: Draft |
| Versie | Datum | Wijziging |
|---|---|---|
| 0.0.1 | 2026-05-05 | Initiële versie |
| 0.0.2 | 2026-05-18 | Verwerking hypothesis-feedback: id_token/token response (#54), open vraag IdP-selectie (#55), "Log in met Koppeltaal"-UX (#56), launch-URL mag gedeeld (#57) |
| Datum | 2026-05-05 |
| Status | Concept |
| Auteur | Roland Groen |
In het huidige Koppeltaal-stelsel worden module-applicaties uitsluitend gestart via een EHR Launch: een portaal (EPD of cliëntportaal) opent de module in de context van een specifieke gebruiker en taak. Dit model werkt goed zolang de interactie met de module altijd via het portaal verloopt.
In de praktijk zijn er echter scenario's waarin een module-applicatie buiten het portaal om contact heeft met de gebruiker — bijvoorbeeld door de gebruiker per e-mail uit te nodigen of door direct een account aan te maken na het detecteren van een nieuwe patiënt. In deze gevallen ontstaat interactie buiten het Koppeltaal-stelsel: er wordt geen launch uitgevoerd, er is geen gecontroleerde contextuele overdracht, en er wordt geen User Authentication AuditEvent aangemaakt.
De SMART on FHIR specificatie biedt hiervoor een gestandaardiseerd alternatief: de Standalone Launch. Hierbij start de app zelfstandig (bijvoorbeeld vanuit een app-icoon, e-mail of browser) en doorloopt alsnog de volledige autorisatie- en authenticatieflow.
Het ondersteunen van de standalone launch naast de bestaande EHR launch adresseert twee concrete behoeften:
last-patient-engagement-extension op Patient.meta. Wanneer interactie buiten de standaard launch-flows plaatsvindt, wordt deze extension niet automatisch door de Koppeltaalvoorziening bijgewerkt en moet de applicatie het veld zelf onderhouden (zie Opschoning Patient-data - startmoment)De SMART App Launch specificatie definieert twee launch-flows:
De gebruiker heeft een actieve sessie in een portaal (EPD, cliëntportaal). Het portaal start de module-applicatie door een browser te openen naar de geregistreerde launch-URL met twee parameters:
iss: het FHIR-endpoint van de Koppeltaalvoorzieninglaunch: een opaque identifier die de sessie koppelt aan de gebruiker en contextDe module ontvangt na autorisatie een token response met daarin het access token (voor toegang tot FHIR-resources), het id_token (met de fhirUser claim wanneer de scope openid fhirUser is aangevraagd), en de SMART context parameters (waaronder patient). Zie SMART launch context parameters. De context is volledig bepaald door het lancerende portaal.
De gebruiker start de module-applicatie zelfstandig — bijvoorbeeld door op een app-icoon te tikken, een link in een e-mail te volgen, of de applicatie direct in de browser te openen. Er is geen portaal dat context meegeeft.
De app doorloopt dezelfde OAuth2-autorisatieflow, maar met twee verschillen:
launch parameter: de app stuurt geen launch-id mee, want er is geen portaalsessielaunch/patient, waarna de autorisatieserver de gebruiker een patiëntselectie kan aanbieden (of de context automatisch bepaalt op basis van de ingelogde gebruiker)De app ontvangt vervolgens dezelfde token response als bij een EHR launch:
fhirUser claim (identiteit van de gebruiker, bij scope openid fhirUser)patient (patiëntcontext)launch-parameter. Dit mag een aparte URL zijn, maar dezelfde launch-URL kan ook beide flows afhandelen op basis van aan- of afwezigheid van de launch-parameterlaunch/patient en openid fhirUser scopes aan om context en identiteit te verkrijgenlaunch-parameter maar met launch/patient scopeDe gebruiker is ingelogd in het portaal. Het portaal selecteert een taak en start de module:
De gebruiker opent de module direct (bijv. via e-mail link of app-icoon):
Een kernprincipe van Koppeltaal is dat alle interactie met patiëntdata via het stelsel verloopt: geautoriseerd, gelogd en traceerbaar. De EHR launch borgt dit wanneer de gebruiker via een portaal werkt. De standalone launch breidt deze borging uit naar scenario's waarin de gebruiker buiten een portaal om wordt bereikt.
Door de standalone launch als gestandaardiseerde route aan te bieden, krijgen module-aanbieders een concreet alternatief voor directe gebruikerscommunicatie die buiten het stelsel om verloopt. In plaats van een eigen onboarding of notificatie die de Koppeltaal-autorisatie omzeilt, kan de module de gebruiker via een "Log in met Koppeltaal"-route alsnog door de volledige SMART on FHIR flow laten gaan. Het resultaat is hetzelfde — de gebruiker komt in de module terecht — maar de interactie is geautoriseerd, de identiteit is vastgesteld, en de activiteit is gelogd.
Bij een EHR launch bepaalt het portaal de patiëntcontext. Bij een standalone launch moet de autorisatieserver dit doen. Voor patiënten die zelf inloggen is dit eenvoudig (de ingelogde gebruiker is de patiënt), maar voor behandelaars of mantelzorgers moet een selectiemechanisme worden geboden. De exacte invulling hiervan moet worden uitgewerkt.
Bij een EHR launch geeft het portaal idp_hint mee op basis van context die alleen daar bekend is — bijvoorbeeld een minderjarige patiënt die via een andere IdP moet inloggen dan een volwassene. Bij een standalone launch ontbreekt deze contextuele hint. Mogelijke routes:
idp_hint mee in het autorisatieverzoek (bijvoorbeeld omdat de uitnodigingscontext bekend is bij de module)De exacte invulling moet worden uitgewerkt, mede in samenhang met het scenario van meerdere IdPs.
Module-applicaties moeten ondersteuning voor de standalone launch registreren bij de Koppeltaalvoorziening, naast hun bestaande EHR launch. Dit kan via dezelfde launch-URL (die beide flows afhandelt) of via een aparte URL. De wijze van registratie (via de bestaande Device-registratie of een apart mechanisme) moet worden bepaald.