3.6 Ontvangen launch context

1. Ontvangen Browser Request

De Aanbiedermodule ontvangt van de PGO de HTTP GET op de launch-url. De URL bevat 2 query parameters.

De Aanbiedermodule MOET de parameter launch door worden behandeld als een opaque string.

https://aanbiedermodule.example.org/web/api/smartonfhir/launch?iss=https://dva-aanbiedersmodules.test.medmij.nl/fhir-proxy launch=47618365135e450480bdca5a72719709

Query Parameter

Waarde

iss

de FHIR Base URL: Dit is het EHR's FHIR endpoint, en dat is in het MedMij Afsprakenstelsel de DVA.

launch

Launch code zoals ontvangen in Token Response van DVA aan DVP.

2. Opvragen smart-confguration

Het opvragen en toesturen van de smart-configuration gebeurt volgens de beschrijving App Launch: Launch and Authorization - SMART App Launch v2.2.0.

De AM stuurt een HTTP GET request naar de DVA.

De aanbiedermodule MOET de waarde van iss gebruiken FHIR Base URL voor het samenstellen van de SMART Discovery URL. De module voegt aan de FHIR Base URL het endpoint .well-known/smart-configuration toe.

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.

3. Verstrekken smart-confguration

De DVA verstrekt de file .well-known/smart-configuration via een HTTP response. Zie kopje Smart Configuration.

Parameter

Waarde

authorization_endpoint

URL van endpoint om Authorization Code Flow te starten

Voorbeeld: https://dva-aanbiedersmodules.test.medmij.nl/identity/connect/authorize

token_endpoint

URL van endpoint om het access_token via Token Exchange op te vragen te verversen.

Bijvoorbeeld: https://dva-aanbiedersmodules.test.medmij.nl/identity/connect/token

token_endpoint_auth_methods_supported

["tls_client_auth"]: vaste waarde in dit S.D. De DVA MOET en MOET ALLEEN mTLS ondersteunen. Deze waarde MOET en MOET alleen ["tls_client_auth"]zijn

4. Doorsturen Browser naar DVA authorization end-point

De Aanbiedermodule stuurt Browser door naar het authorization_endpoint, door het sturen van een HTTP/1.1 302 Found met de redirect URL.

De AM MOET de redirect URL opgeven waarvan de FQDN naar zichzelf verwijst. De Browser stuurt hiermee een RFC6749 Authorization Request naar de DVA. De URL bevat de query parameter launch met de launch code verkregen in 3.4.

De DVA MOET checken of deze redirect naar de AM verwijst, en MOET deze exacte URL gebruiken voor de latere redirect.

In het verzoek op /authorize vraagt module om toegang tot scopes. De module heeft een referentie naar de gebruiker (Patient/<id>) nodig binnen FHIR. om de Taak gegevens op te kunnen vragen. Dat gebeurt via de scopes launch/patient, openid en fhirUser. De sub in de Authorization server is een ander ID dan de patient/id in de Resource server.

AM heeft resource scopes als ‘clinial scopes’ system/Task.* en patient/Patient.read voor toegang tot resources zoals bijvoorbeeld FHIR Task. De keuze van scopes moeten voldoen aan het principe van Least Privilege. Daarom MAG de AM NIET om scope profile vragen.

De DVA ontvangt met dit Authorization request automatisch het Authenication cookie dat gezet is tijdens het ophalen van de launch code door de DVP, door middel van de Authorization code flow tussen de Browser, DVP en DVA.

Query Parameter

Waarde

launch

de Launch code die verwijst naar launch context; ontvangen in 3.4

scope

system/Task.* patient/Patient.read launch launch/patient openid fhirUser vaste waarde, vereist om de gebruikersidentiteit als referentie naar FHIR-resource te ontvangen

system/Task.*: clinical scope, zodat AM de Task zowel kan lezen als schrijven om de status te updaten

patient/Patient.read: clinical scope, zodat AM de Patient gegevens kan lezen

launch: zodat launch context meekomt

launch/patient: zodat patient value meekomt in Token Response (optioneel)

openid: zorgt voor claim sub in token (of geregisteerd in DVA bij het token).

Ter informatie: Een openid scope geeft ook een id_token, met claims over de gebruiker. Voor precieze invulling, zie beschrijving Gegevensdienst.

fhirUser: zorgt dat claim fhirUser mee terugkomt in token (of geregisteerd in DVA bij het token)

client_id

client_id van de AM, verwijzend naar de module zelf. Bijvoorbeeld: dvaaanbiedersmodulesweb,

redirect_uri

de URL verwijst naar callback op AM, waar de Browser naar toe moet na het ontvangen van een positief Authorisation Response

Bijvoorbeeld: https://module.5im.nl/web/api/smartonfhir/callback

response_type

code vaste waarde per RFC

state

random waarde per SMART App Launch standaard

code_challenge

PKCE challenge per RFC7636; AM moet een random value code_verifier genereren, bewaren en in Token Request meesturen.

Bijvoorbeeld: 2ZgbO_-Qzwo5ly4ylWKgnxKLDXqeWlkJEFoTWw1lDNU

code_challenge_method

S256 vast waarde; PKCE in dit S.D. gebruikt altijd SHA256.

nonce

random value, als per RFC. De AM controleert of dit in het token terugkomt in het id_token.

aud

audience - dit is dezelfde waarde als de iss parameter in de SMART launch URL (DVA doet hier gewoonlijk niets mee, en logt dit).

5. Verzoeken om Autorisatie

De Browser stuurt automatisch een GET met een Authorization Request door middel van het volgen van de redirect URL uit de vorige stap. Dit start de RFC6749 Authorization Code Flow.

Het mechanisme van de Browser, stuurt automatisch het Authentication cookie, gezet eerder in het proces, mee met het verzoek. Dit ligt vast in de HTTP standaard.

6. Authenticatie (7 en 8 vervallen)

De DVA voert de Authenticatie uit.

Optie Authentication cookie: De DVA MOET het Authentication cookie checkten tegen de volgende voorwaarden:

1. het cookie is nog geldig

2. de Authentication code in het cookie is gelijk aan de cookie registratie in de DVA.

3. de Launch code hoort bij het cookie.

4. het client_id van de AM hoort bij het cookie.

Voldoet het cookie aan deze checks, dan:

• keurt de DVA de authenticatie goed, en

• MOET de DVA het registratie van dit cookie vernietigen, en

• MOET de DVA deze Authorization correleren met de Persoon die bij het MedMij_Verzamlen_Token hoort waarvoor het cookie is afgegeven en met de launch context waarvoor de Launch code is afgegeven.

Een DigiD login proces door de DVA valt buiten scope van dit S.D.

9. Toekennen (of afwijzen) authenticatie en doorsturen Browser naar AM token endpoint

Na succesvolle authenticatie en toestemming stuurt de DVA naar de Browser een positief RFC6749 Authorization Response, met payload volgens de HL7 SMART App Launch standaard. Dit response bevat een redirect naar de Aanbiedermodule ten behoeve van de AM-DVA Token Exchange, met de autorisatie code.

De DVA moet de redirect URL ontvangen van de AM gebruiken en controleren of deze bij de AM hoort, zie aldaar.

Bij een succesvolle authenticatie, stuurt de DVA een positief Authorization Response.

Faalt de authenticatie, dan stuurt de DVA een negatief Authentication Response, HTTP 400 Bad Request Response, als beschreven in RFC 6749 - The OAuth 2.0 Authorization Framework, section 4.1.2.1. Error Response.

(Query) Parameter

Waarde

HTTP response code en text

302 Found

Location

de URL uit redirect_uri

code

random waarde, ter controle bij aanvraag Token Request

Bijvoorbeeld: A970E84A8878AD542902D49B1A537EA6A730BA15735E2582F2A3A1933BB6BFBE-1

state

waarde zoals ontvangen in Authorization Request

scope

zelfde als in Authorization Request; DVA MAG besluiten minder scopes toe te kennen als het hiervoor een goede reden heeft.

Bijvoorbeeld: system/Task.* patient/Patient.read openid fhirUser launch launch/patient

10. Uitvoeren redirect naar Aanbiedermodule

Browser volgt automatisch met een GET de juist verkregen URL uit de 302 Found response.

11. Opvragen access_token met launch context

Het uitwisselen van de launch context is het tweede deel van de Authorization code flow en gebeurt met een RFC6749 Access Token Request en Response, opnieuw met payload volgens de HL7 SMART App Launch standaard.

De Aanbiedermodule stuurt een Access Token Request met een /token-verzoek op het token_endpoint met de authorization code. De DVA genereert een access_token voor FHIR-toegang op dezelfde wijze als een token voor MedMij verzamelen.

Omwisselen van code voor context gebeurt met een OIDC Token Request bij de opgegeven issuer. De AM en DVA MOETEN op basis van RFC8705, Mutual TLS, authenticeren.

AM MOET method POST gebruiken.

(Query) Parameter

Waarde

method

POST

grant_type

authorization_code

code

random waarde zoals ontvangen van DVA in Authorization Response, en doorgestuurd door Browser als query parameter
Bijvoorbeeld: A970E84A8878AD542902D49B1A537EA6A730BA15735E2582F2A3A1933BB6BFBE-1

redirect_uri

endpoint om Browser naar toe te sturen na Token Exchange Response.

Bijvoorbeeld: https://module.5im.nl/web/api/smartonfhir/callback

code_verifier

PKCE die hoort bij het Authorization Request

Bijvoorbeeld: 0bcuhhET_MCknrc-Rxd-IfHlRdFfWpaNF_0C_xPfXVM

12. Validatie token verzoek

De AM valideert het verzoek tegen de volgende condities:

1. code_verifier MOET horen bij PKCE code_challenge uit het Authorization Request

2. code (authorisatie code) MOET overeenkomen met uitgegeven code in de Authorization Response

Faalt deze validatie, dan MOET de DVA het Token Request afwijzen.

13. Toekennen access_token en launch context

Token response bevat de launch_context met de parameters in JSON formaat in de HTTP body.

Na ontvangst van de token-response MOET de aanbiedermodule controleren dat de waarde van issuer in de token-response 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.

Heeft de validatie van het tokenverzoek gefaalt, dan stuurt de DVA een Error Reponse, als beschreven in RFC 6749 OAuth 2.0 Sectie 5.2 Error Response.

(Query) Parameter

Waarde

method

POST

access_token

random waarde

Let op: Op tokens is verantwoordelijkheid core.autorisatie.205 van toepassing.

token_type

vaste waarde, Bearer

expires_in

geldigheidsduur van het token: Zie ook voor geldigheidsduur paragraaf 3.8.

intent

startmodule vaste waarde per dit S.D.

resource

de resource waar het over gaat

Bijvoorbeeld: Task/350755BC-E573-4004-91A3-91321E4BCA2A

return_url

de url waar de gebruiker terug gestuurd kan worden.

DVA MOET FQDN van return_url verifieren tegen de whitelist in het MedMij register.

De DVA MAG ALLEEN de return_url aan de Aanbiedermodule doorsturen die van de DVP ontvangen is.

Bijvoorbeeld: https://pgo-aanbiedersmodules.test.medmij.nl/web?dvaname=medrie

id_token

identiteitstoken van de gebruiker; is een JWT token. Bevat onder meer het volgende:

sub de ID van Persoon in Authorisatie Server

fhirUser de Patient.Id van Persoon in FHIR server, voorbeeld Patient/XXX_Patient

n.n.t.b.

scope

zoals in Authorization Reponse (of Token Request?)

Bijvoorbeeld: dvaaanbiedersmodules openid fhirUser launch launch/patient

patient

uit de scope launch/patient, FHIR patient vanuit gekoppeld vanuit de sub, gekoppeld aan.
Bijvoorbeeld: "ProviderModule-Patient-Van-Duinen"

14. tot en met 16. Verzamelen en toesturen Taak

De AM gebruikt het acess_token om de Taak bij de FHIR resource server op te halen bij de DVA. Dit is beschreven in 3.7 en/of 3.8, en hier alleen toegevoegd voor context. AM gebruikt de launch context om applicatie op te zetten voor de bezoekende gebruiker. Zie 3.3 voor het Verzamelen van taken en specifieke opmerkingen ten aanzien van de AM.

17. tot en met 19 Tonen van de Taak

Heeft de AM de Taak ontvangen, dan kan de AM een response met een webpagina naar de Browser sturen om deze Taak te tonen en te laten uitvoeren. De layout, parameters en verdere implementatie is de verantwoordelijkheid van de AM.