3.6 Ontvangen launch-context

1. Ontvangen gebruiker

Aanbiedermodule ontvangt de gebruiker met een browserverzoek op de launch-url. De module leest de EHR's FHIR endpoint en launch-code uit.

https://aanbiedermodule.example.org/web/api/smartonfhir/launch?iss=resourceserver.example.dva.nl&launch=launch-code

2. Uitlezen smart-config

De aanbiedermodule MOET de waarde van iss gebruiken als startpunt voor SMART Discovery.
Deze waarde bepaalt de FHIR-base en de SMART metadata, via EHR's FHIR endpoint: .well-known/smart-configuration

In deze discovery verzamelt module het authorization_endpoint, issuer en token_endpoint van DVA voor de OIDC-authorization code flow en token request op 3.6 Ontvangen launch-context | 6.-Uitwisselen-launch-context .

Na het bepalen van de endpoints begint module een SMART on FHIR authorization code flow met gebruikersidentificatie bij issuer (DVA). De volgende processtappen lichten dit toe.

De launch-parameter MOET door de module worden behandeld als een opaque string.
De module mag deze niet parsen of interpreteren, maar stuurt de waarde ongewijzigd door naar het authorization_endpoint.

De module mag pas na ontvangst van de token-respons bepalen hoe de launch-context moet worden geïnterpreteerd.
Dit is noodzakelijk omdat zowel MedMij als Koppeltaal dezelfde launch-flow gebruiken, maar verschillende vormen van token-responses teruggeven.

3. Doorsturen gebruiker naar DVA voor autorisatie-flow

Module stuurt gebruiker door naar het authorization_endpoint.

Afhankelijk van de context waar de gebruiker in opereert hebben we 2 scenario’s.

Afhankelijkheid van scenario-keuze

Welke vorm van launch-context wordt gebruikt, wordt bepaald door de DVA/zorgaanbieder.
De module heeft hierin geen keuze: de DVA bepaalt welke informatie noodzakelijk is voor de taak en dus welke scopes vereist zijn.

Een SMART launch kent daarom twee mogelijke scenario’s waar een module mee moet kunnen omgaan:

Scenario 1 — Module voert alleen een taak uit (geen gebruikersprofiel nodig)

(door de DVA gekozen wanneer de module geen kennis van de gebruiker hoeft te hebben)

In dit scenario geeft de DVA alleen taakgerelateerde informatie terug. De module hoeft de gebruiker niet te identificeren en vraagt daarom geen openid / fhirUser.

De module gebruikt uitsluitend de taak-ID en vereist alleen de resource-scopes die nodig zijn om de taak te lezen en te voltooien.
Er is geen id_token nodig en geen OIDC-functionaliteit.

In het verzoek op /authorize vraagt module om toegang tot scopes

• scope launch: de launch-code die verwijst naar launch-context.

• resource scopes als patient/*.read en system/Task.* voor toegang tot resources zoals bijvoorbeeld FHIR Patient en Task. Zie https://build.fhir.org/ig/HL7/smart-app-launch/scopes-and-launch-context.html

• niet scopes: openid, profile, fhirUser

Effect:

• Module gebruikt taak ID en schrijft data terug in FHIR server

• DVA moet minimaal browser authenticatie doen (step-up), als het geen open link moet zijn

• Gebruiker ziet hier niks (zijn directe redirects), en zou als naam “PGO-gebruiker” kunnen tonen.

Scenario 2 — Module heeft gebruikersidentiteit nodig (bijv. eigen profiel, personalisatie, logging)

(bijv. modules die willen weten wíe de gebruiker is, of wanneer resultaten gekoppeld worden aan een gebruikersaccount in de module)

In dit scenario heeft de module een referentie naar de gebruiker nodig binnen FHIR, bijvoorbeeld:

• Patient/<id> wanneer de gebruiker de patiënt is

• Practitioner/<id> wanneer de module gebruikt zou worden door zorgverleners (later scenario)

Dit gebeurt via de scope openid fhirUser.

• scope openid fhirUser: vereist om de gebruikersidentiteit als referentie naar FHIR-resource te ontvangen (Patient/XXX_Patient).

• niet scopes: profile

• De DVA moet hier identificatie en authenticatie doen (waarschijnlijk met DigiD, maar niet verplicht)

• Er is wel een id_token met een claim over de gebruiker (zou ook BSN kunnen zijn)

Aanvullende uitwerking volgt. In gesprek met ontwikkel-
partners bepalen we of de scopes optioneel worden.

4. Verifiëren toestemming

DVA valideert de launch-code na ontvangst van het verzoek op authorization-endpoint. DVA gaf de launch-code in 3.4 Aanvragen launch-code af en correleert dit met het originele access_token en de launch_context.

DVA verifieert of gebruikerstoestemming is gegeven op het starten en uitwisselen met module. Als nodig start DVA gebruikersidentificatie langs DigiD en toestemmingsverklaring voor gegevensdeling met specifieke module.

5. Uitwisselen auth-code

Na succesvolle identificatie en toestemming volgt een redirect van gebruiker naar module met de authorization code. Bij voortijdig afbreken of fouten in de aanvraag volgt een error-respons als beschreven in RFC 6749 OAuth 2.0 Error Response.

6. Uitwisselen launch-context

Omwisselen van code voor context gebeurt met een OIDC Token Request bij de opgegeven issuer. De issuer (DVA) en aanbieder-
module vertrouwen elkaar en passen beveiligingseisen toe die passen bij de verwerkingsverantwoordelijkheid van zorgaanbieder.

Module doet een /token-verzoek op het token_endpoint met de authorization code. Module authenticeert zich via client credentials of JWT-token, DVA genereert een access_token voor FHIR-toegang.

Token response bevat altijd - ongeacht welk scenario van stap 3- de launch_context met deze velden in JSON:

• access_token: voor toegang tot FHIR-resources binnen scopes.

• token_type: vaste waarde, “Bearer”.

• expires_in: geldigheidsduur van het token.

• intent: smartmodule (fixed value)

• resource: Geeft de resource terug waar het over gaat (Task/350755BC-E573-4004-91A3-91321E4BCA2A)

• return-url:de url waar de gebruiker terug gestuurd kan worden

• Andere contextparameters, zoals encounter als van toepassing.

Aanvullend bij scenario 1:

• patient: FHIR Patient.Id uit de launch-context.

Aanvullend bij scenario 2:

• fhirUser: FHIR-referentie naar de gebruiker, doorgaans gelijk aan patient (Patient/XXX_Patient), mogelijk ook zorgverlener (out-of-scope, bijvoorbeeld Practitioner/XXX_Zorgverlener).

• id_token: identiteitstoken van de gebruiker

Na ontvangst van de token-respons MOET de aanbiedermodule controleren dat de waarde van issuer in de token-respons gelijk is aan de issuer uit de SMART Discovery:

token_response.issuer == smart_configuration.issuer

Let op:

• Dit is niet de waarde uit de oorspronkelijke iss= queryparameter.

• Deze controle is verplicht binnen SMART App Launch ter bescherming tegen mix-up attacks.

• De controle is van toepassing op zowel MedMij- als Koppeltaal-implementaties.

• Bij Koppeltaal kan het access_token zelf een vaste NOOP-waarde zijn; de issuer-check blijft verplicht.

7. Starten module

Aanbiedermodule gebruikt de launch-context om applicatie op te zetten voor de bezoekende gebruiker. Aanbiedermodule kan de verwijzingen naar taak gebruiken om met zorgaanbieder meer gegevens uit te wisselen en resultaten te bewaren.

Bij een module met vragenlijst kan bijvoorbeeld een voornaam getoond, tussentijds resultaten bewaard en een gereedmelding opgeslagen bij zorgaanbieder.

8. Bijwerken taak

Aanbiedermodule wijzigt taakstatus bij zorgaanbieder. Zie 3.7: Wijzigen taakstatus.
Gebruiker verzamelt in PGO de status van aanbiedertaken bij DVA.