3.4 Ophalen Launch code en Authentication cookie

1. Persoon start taak

Persoon start Taak. Dit S.D. vermeldt deze stap om de context duidelijk te maken.

De Browser stuurt een HTTP message naar de DVP/PGO applicatie. De methode en inhoud van het bericht valt onder de verantwoordelijk van de PGO leverancier en buiten dit S.D.

De PGO MOET de persoon erop wijzen dat de Taak opent buiten controle van de PGO.

2. Validatie geldig access_token op DVP

DVP stuurt RFC9216 Pushed Authorization Request.

De DVP MOET een POST gebruiken voor dit Request.

De DVP MOET het Request beveiligen met PKCE (RFC7636). Deze komt terug bij de Token Exchange Request.

Dit MedMij verzamelen access token wordt gevalideerd door DVA of deze geldig en niet verlopen is. Het token bevat een sub, die vertelt welke Persoon hierbij hoort.

3. Validatie response

DVA stuurt DVP een Authorization Response. De volgende stap gebruikt de URI inclusief code om een de autorisatie aan te vragen.

4. Redirect naar DVA

De DVP redirects de Browser naar de DVA voor Authorization Code Flow.

5. Autorisatie Request door Browser

De Browser stuurt n.a.v. de redirect een Authorization Request naar het DVA /authorize endpoint.

6. Aanmaken cookie

De DVA genereert een Authentication cookie.

De DVA koppelt dit aan:

• De claim sub; dit is het subject id uit het valide MedMij Verzamelen Token, opgeslagen in de DVA authorisatie server.

• client_id module, komt uit de audience parameter van het PAR Request, en op haar beurt haalde de DVP deze uit het FHIR endpoint resource van de gegevensdienst Taak, die verzameld is in het verzamelen proces.

• de code van de Authorization Code Flow, door DVA aangemaakt.

De DVA noteert dat het cookie nog niet actief is, wat betekent dat wanneer het cookie nu gebruikt zou worden, de DVA het als ongeldig beschouwd.

De DVA MOET het cookie vernietigen als het het cookie terugontvangt voordat de het actief is.

MaxAge is 60 s. (of Expires = nu + 180 s).

7. Toesturen cookie en redirect naar Token Exchange

De DVA stuurt een redirect naar de Browser, met daarin het Authentication cookie en de redirect URL, inclusief code en state voor de Token Exchange tussen DVP en DVA.

8. Browser request DVP met authorization code

Browser volgt zojuist ontvangen redirect.

9. Opvragen Launch code

De DVP gebruikt de informatie van de Browser op het callback endpoint, en stuurt een Token Exchange Request volgens RFC8693.

subject_token bevat MedMij Verzamelen Token

De DVA MOET de geldigheid van het MedMij Verzamelen Token valideren.

Waarom? Taken bedoeld in de context van aanbiedermodules zijn gebonden aan aanbiedermodules-applicaties waar PGO geen directe communicatie mee heeft. Deze applicaties communiceren in het domein van Zorgaanbieder en vallen onder verwerkersverantwoordelijkheid van de Zorgaanbieder.

Met het aanvragen van een Launch code voor Persoon geeft DVP een context mee aan DVA: Om welke persoon gaat het, welke taak wil deze uitvoeren en met welke PGO werkt de persoon? Deze informatie wordt gelogd, geverifiëerd en als nodig kan DVA op basis van de context vragen om aanvullende identificatie, toestemmingen die passen bij interactie op taak tussen Persoon en aanbiedermodule-applicatie.

10. Valideren Launch code verzoek

DVA valideert het request, tegen de volgende parameters

• het Token Request MOET matchen met het Authorization Response

• authorization code (parameter naam: code) MOET gelijk zijn aan de authorization code (naam: code) in Authorization Response

• code_verifier MOET horen bij PKCE code_challenge uit het PAR Request

• FQDN van de return_url MOET verwijzen naar de PGO zelf.

De DVA genereeert een Launch code en onthoudt dat deze code bij het Authentication cookie hoort.

De DVA activeert het Authentication cookie, wat inhoudt dat vanaf nu het cookie gebruikt mag worden.

11. Uitgeven Launch code

DVA stuurt een Token Exchange Response met de Launch code in het veld access_token.

Bij een fout, wijst de DVA de aanvraag voor een Launch code af met een fout, volgens de sectie parameters.

De PGO applicatie toont een foutscherm, zie weergaverichtlijn.

12. Response met redirect naar Taak module

De DVP stuurt een 302 Found redirect response op de Browser call_back, met Taak module endpoint en Launch code.

De DVP/PGO MOET de de query parameter launch toevoegen met de value van het element access_token.

De DVP/PGO MOET het endpoint uit de acitvity definition gebruiken als launch-URL voor het starten van de Aanbiedermodule. Het endpoint is de value van het element extenstion.url die hoort bij element extension.valueReference.type = Endpoint. De Endpoint waarde heeft de PGO van de DVA ontvangen in 3.3 Verzamelen aanbiedertaken.

De DVP/PGO MOET de de query parameter iss toevoegen met de value afkomstig van response token FHIR_base_url, zie:3.4 Ophalen Launch code en Authentication cookie | fhir_base_url.

Zoals gezegd in de paragraaf https://medmij.atlassian.net/wiki/spaces/Toolbox1/pages/854065173, MOET de PGO ook duidelijk maken dat de Persoon naar een andere vertrouwensomgeving gaat.

subject_token

MEDMIJ_VERZAMELEN_TOKEN

audience

module client_id; dit komt uit de de PAR

response_type

code (RFC vaste waarde)

acr_values

urn:medmij:oauth2:acr-value:launch-authorization vaste waarde per dit S.D. Zie ook RFC8176.

Zodat DVA weet dat dit request voor een Aanbiedermodule Launch code ophalen process.

state

random waarde met een entropie van 128-bit. Gebruikt zoals voorgeschreven in de OAuth 2.0 RFC.

client_id

DVP client_id welke DVP per A.S. gekregen heeft. Bijvoorbeeld pgo-aanbiedermodules of meestal het volledige domein van de PGO applicatie leverancier, zoals bijvoorbeeld: mijnpgo.nl.

redirect_uri

Volledige URL verwijzend naar de endpoint waar de Browser naar toe moet voor de Token Exchange.

Bijvoorbeeld https://pgo-aanbiedersmodules.test.medmij.nl/web/api/dvamod/launch-callback.

scope

Voor welke DVA dit PAR bestemd is. Dit is de naam van de Zorgaanbieder uit de ZAL (maar dan zonder @medmij.nl suffix). Bijvoorbeeld: dvaaanbiedersmodules

PKCE

Lijst met twee waarden (<code_challenge>,<code_challenge_method>)

acr_values

urn:medmij:oauth2:acr-value:launch-authorization vaste waarde per S.D. Zie ook RFC8176.

Zodat DVA weet dat dit request voor een Aanbiedermodule Launch code ophalen process.

HTTP response code en text

201 CREATED PAR request successful

RequestUri

urn:ietf:params:oauth:request_uri:<random>, waar <random> is een random waarde met een entropie van 128-bit. Deze is om Authorisatie Request in de Authorization Code Flow in de volgende stap te kunnen koppelen aan de PAR.

Bijvoorbeeld: urn:ietf:params:oauth:request_uri:B02D0740E140AD2AB131610F5428E43BE1FFBBD35BDA3ED2CF0DD863EDF1C19D

ExpiresIn

60 vaste waarde, tijd in seconden

client_id

<dvp_client_id> zoals gebruikt in PAR Request

request_uri

waarde verkregen in PAR Response. Bijvoorbeeld:

urn:ietf:params:oauth:request_uri:B02D0740E140AD2AB131610F5428E43BE1FFBBD35BDA3ED2CF0DD863EDF1C19D

state

Deze waarde is gelijk aan de waarde in het PAR request. De DVA MOET het request afwijzen als de waardes ongelijk zijn. Bijvoorbeeld:

8dce3d3396989c1a86c419cafee480157c47180743f342442c966e6ee3ff2889

HTTP response code en text

302 Found

Location

De redirect_uri uit het PAR Request. Per A.S. MOET de DVA deze verifiëren met de tag <redirect_uri> van de gegevensdienst in de OAuth client list.

Bijvoorbeeld: https://pgo-aanbiedersmodules.test.medmij.nl/web/api/dvamod/launch-callback

Note: nu is er nog slechts 1 redirect URI in de lijst, mogelijk extra toevoegen.

code

een random waarde met een entropie van 128-bit. Gebruiken als per RFC.

Bijvoorbeeld: b756ad1809264cd182b1c4a8c7951caf

state

de waarde uit het request. Bijvoorbeeld: 8dce3d3396989c1a86c419cafee480157c47180743f342442c966e6ee3ff2889

smart_launch_context

Context heeft drie parameter in JSON formaat, zodat de DVA deze informatie weet bij het starten van de Taak. Context resource komt vanuit de verzamelde Taak. Parameter intent is per S.D. vaste waarde (deze parameter is nog in ontwikkeling). Parameter return_url bepaalt de DVP zelf en is de locatie waarop Aanbiedermodule de Browser later terug zal sturen naar de PGO.

Bijvoorbeeld:

{
  "resource": "Task/ProviderModule-SubTask-Meetopdracht-Bloeddrukmeting-13",
  "intent": "startmodule",
  "return_url": "https://pgo-aanbiedersmodules.test.medmij.nl/web?dvaname=medrie"
}

De FQDN van de return_url MOET verwijzen naar de PGO zelf.

De DVA MOET verifiëren dat FQDN van de return_url naar de PGO zelf verwijst (de DVA heeft deze informatie in het certificaat dat mTLS gebruikt) en dat de FQDN onderdeel is van het MedMij register.

grant_type

urn:ietf:params:oauth:grant-type:token-exchange vaste waarde per RFC

subject_token

<MEDMIJ_VERZAMELEN_TOKEN>: het access_token van de Persoon die op dit moment de PGO applicatie gebruikt. De DVA registreert dat dit token bij de launch context hoort.

subject_token_type

urn:ietf:params:oauth:token-type:access_token vast waarde per AS

actor_token

de opaque authorization code: de waarde uit het ACF Authorization Response. Bijvoorbeeld: b756ad1809264cd182b1c4a8c7951caf

actor_token_type

urn:medmij:token-type:authorization-code vaste waarde per dit S.D.

requested_token_type

urn:medmij:token-type:launch-code vast waarde per dit S.D.

client_id

dezelfde waarde als in het PAR request en ACF Authorization Request

audience

het client-id van de Taak module, verkregen uit valueString van ActivityDefinition.extension[x].url = http://medmij.nl/fhir/StructureDefinition/client-id

scope

Voor welke DVA dit Token Request bestemd is. Dit is de naam van de Zorgaanbieder uit de ZAL (maar dan zonder @medmij.nl suffix), gelijk aan scope in gebruik voor Verzamelen. Zie ook https://afsprakenstelsel.medmij.nl/asverplicht/mmverplicht/token-interface. Voorbeeld: dvaaanbiedersmodules

code_verifier

een random waarde met een entropie van 128-bit. Dit om te testen tegen de eerder ontvangen PKCE, zoals gebruikelijk in Authorization Code Flow. Bijvoorbeeld: 0bcuhhET_MCknrc-Rxd-IfHlRdFfWpaNF_0C_xPfXVM

response_type

code vaste waarde per

HTTP response code

200 OK

access_token

Dit is de Launch code, een random waarde met een entropie van 128-bit. Bijvoorbeeld: 47618365135e450480bdca5a72719709.

Let op: Deze parameter moet volgens de RFC access_token heten, en bevat dus geen token, maar de Launch code.

expires_in

60 vast waarde, tijd in seconden dat de Launch code geldig is. De DVA en DVP MOETEN de expiratie tijd berekenen aan de hand van de interne klok plus de waarde van expires_in, die 60 seconden is.

token_type

N_A vaste waarde per RFC

scope

zelfde als uit Request

issued_token_type

urn:medmij:token-type:launch-code vaste waarde voor dit S.D. Dit geeft aan dat het uitgegeven token een MedMij Launch code betreft.

fhir_base_url

De volledige URL van FHIR interface van de DVA verwijst.

De aanbiedermodule MOET deze URL gebruiken voor de constructie van de SMART on FHIR configuratie discovery-URL door /.well-known/smart-configuration hieraan toe te voegen.

Bijvoorbeeld: https://dva-aanbiedersmodules.test.medmij.nl/fhir-proxy

HTTP Response code en text

302 Found

Location

endpoint naar Aanbiedermodule; deze komt uit de FHIR endpoint resource

Query Parameter

Waarde

iss

het endpoint van de DVA Resource Server; door DVP uit <ResourceEndpointuri> tag van gegevensdienst Aanbiederstaken in ZAL gehaald.

launch

de Launch code, die waarde van access_token is, ontvangen in de Token Exchange Response.