3.4 Aanvragen launch-code
Besluit een gebruiker in te gaan op de uitnodiging van een zorgverlener, dan stuurt de PGO de gebruiker naar de aanbiedermodule met een launch-code. De launch-code verwijst naar een eenvoudige launch-context die PGO bij DVA vastlegt met een token exchange. Hierin staat informatie over welke taak voor welke patiënt de aanbiedermodule moet uitvoeren.
Processtappen
Gebruiker bezoekt de aanbiedermodule met een launch-code dat verwijst naar een context bij DVA. Deze launch-context vastleggen gebeurt in OAuth2 met Token exchange-interface en Step-up.
Processtap | Toelichting |
|---|---|
1. Persoon kiest taak | Persoon kiest aanbiedertaak en is er mee bekend dat dit de aanbiedermodule-applicatie opent buiten controle van de PGO. In het taakoverzicht staat wie de taak aanbiedt en de aanbiedermodule-applicatie beheert. |
2. Launch-code halen | DVP vraagt bij DVA een launch-code op voor de aanbiederstaak middels token request. 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 wat lichte 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. Zie toelichting en advies voor Dienstverleneraanbieder. |
3. Step-up afhandelen | DVA kan er voor kiezen geen launch-code terug te geven, maar in plaats daarvan een stepup-error te retourneren. De foutrespons geeft dan met Zie ook: 3.4 Aanvragen launch-code | Step-up-flow: Waarom? Toekomstbestendigheid. Optionele feature voor toekomstige scenario's. Usecase: wanneer DVA extra verificatie nodig acht voor gevoelige modules of specifieke gegevenstoegang. |
4. Fouten afhandelen | DVA kan de aanvraag voor een launch-code afwijzen met een fout. Specifiek beschrijft RFC 6749 beschrijft de errors:
Dienstverlenerpersoon toont een foutscherm, zie weergaverichtlijn. |
Procesdiagram
Procesdialoog
Zie RFC6749 voor error-respons. Merk op dat de afgegeven launch-code (medmij:token-type:one-time-code) hier van het type NA is, niet Bearer ("token_type": "NA").
2. Launch-code verzamelen met token request
Accept: application/json
Content-Type: application/x-www-form-urlencoded
POST https://dvauth.example.org/token
smart_launch_context = {
"resource": "Task/350755BC-E573-4004-91A3-91321E4BCA2A",
"intent": "startmodule",
"return_url": "https://pgo.example.org/launch_callback"
}
grant_type = urn:ietf:params:oauth:grant-type:token-exchange
subject_token = eyJhbGciOimtpZCI6I.eyJpc3MiOiJodHRwczovL2xv.YIGha3yI3qEHwysjuw
subject_token_type = urn:ietf:params:oauth:token-type:access_token
client_id = example_client_id_dvp
audience = example_client_id_module
scope = dvanaam
requested_token_type = urn:medmij:example:launch-code
iss = issuer.example.org
200 OK
{
"access_token": "9c22a827e63e4139bcf3a03d7e787d71",
"expires_in": 60,
"token_type": "NA",
"scope": "scope",
"issued_token_type": "urn:medmij:example:launch-code"
}
400 Bad Request
{
"error": "invalid_request",
"error_description": "Onjuiste aanvraag"
}
400 Bad Request
{
"error": "invalid_request",
"error_description": "Algemene fout in verzoek: log en toon foutmelding"
}
Step-up flow:
De step-up is een optionele uitbreiding binnen de bestaande Token Exchange flow.
De parameter step_up_code wordt toegevoegd aan het token-request wanneer de DVA een invalid_grant response retourneert met error_uri die duidt op een step-up. Er worden geen nieuwe grant types geïntroduceerd. Het mechanisme blijft conform RFC 8693 en RFC 6749.
3.1: Step-up afhandelen bij een invalid_grant
repsonse ontvangen:
400 Bad Request
{
"error": "invalid_grant",
"error_description": "Step up: pas eerst gewone authorization code flow toe",
"error_uri": "https://example.org/errorcodes/invalid_grant_step-up"
}3.2 Start step-up
De DVP start een nieuwe Authorization Request naar het authorization_endpoint dat bij deze token_endpoint hoort (diegene die hij uit de ZAL vond voor Taken), met de volgende query parameters:
response_type = urn:medmij:example:oauth2:response-type:step-up
client_id = <zelfde dvp_client_id>
redirect_uri = <zelfde dvp_redirect_uri>
scope = <zelfde scope als Token Exchange>
state = <random_state>
code_challenge = <PKCE_challenge>
code_challenge_method = S2563.3 Afhandeling door DVA
De DVA bepaalt zelf wat er tijdens de step-up gebeurt:
Plaatsen van een cookie om een browser te herkennen (security-fix).
Tonen van een toestemmings- of informatiescherm aan de gebruiker.
Er vindt geen login plaats tijdens deze stap.
Na afronding redirect de DVA terug naar de redirect_uri:
?step_up_code=<opaque_code>&state=<state>3.4 Tweede Token Exchange
De DVP herhaalt de Token Exchange met extra parameters:
step_up_code= <code_from_redirect> //de code die je uit de vorige stap hebt gekregen
code_challenge_verifier = <PKCE_verifier>
//(DVA dient combinatie van step up code + code challenge verifier te checken)De DVA valideert deze combinatie (step_up_code + PKCE) en koppelt deze aan de eerdere context.
3.5 Launch code ontvangen
Na succesvolle validatie geeft de DVA een reguliere response terug:
200 OK
{
"access_token": "9c22a827e63e4139bcf3a03d7e787d71",
"expires_in": 60,
"token_type": "NA",
"scope": "scope",
"issued_token_type": "urn:medmij:example:launch-code"
}
Let op: N.N.T.B of de module door verschillende partijen wordt aangeroepen en dit onderscheid willen maken met intent
Parameters
Bij het gebruik van https://datatracker.ietf.org/doc/html/rfc8693 maken we gebruik van de volgende parameters (sectie 2.1):
Parameter | Waarde |
|---|---|
smart_launch_context | De context om te registreren bestaat uit een intent en FHIR-resource die aanbiedermodule na de launch informeren over de te starten taak. Opgemaakt in JSON, geeft PGO optioneel ook een terugkeeradres.
|
grant_type | Vaste waarde, |
subject_token | De huidige |
subject_token_type | Vaste waarde, |
client_id | example_client_id_dvp |
audience |
Voorbeeld: dvamodule Let op: dit is nog een voorbeeld url! |
scope | Gelijk aan scope in gebruik voor Verzamelen (de aanbiedernaam uit ZAL zonder @medmij). Zie ook https://afsprakenstelsel.medmij.nl/asverplicht/mmverplicht/token-interface. Voorbeeld: |
requested_token_type | Vaste waarde, |
response_type | urn:medmij:oauth2:response-type:step-up Het |
issuer |
requested_token_type: nader te bevestigen/registeren
15-11-2025: In deze response moet nog een extra veld met de FHIR base URL (de root waarop je ./well-known/smart-configuration toevoegt)
Suggestie: gebruik hiervoor de key fhir_base_url_iss of fhir_base_url.
Dit is de waarde die in 3.5 Starten aanbiedermodule gebruikt wordt in de iss URL parameter.
TIP: Voeg ook zo’n tabel toe voor de expected response, ipv alleen het voorbeeld in de codeblock.
Note: Het is toegestaan custom outputs toe te voegen ( The client MUST ignore unrecognized value names in the response., https://www.rfc-editor.org/rfc/rfc6749#section-5.1 )
Aanvullende uitleg
In het functioneel ontwerp onderscheiden wij verschillende typen aanbiedermodules. Het technisch ontwerp beperkt zich voor nu tot usecases waarbij Persoon een module start op uitnodiging van zorgverlener (taak). Deze uitnodiging kan een patiënt op verschillende manieren bereiken, bijvoorbeeld in een e-mail, brief of een persoonlijk gesprek. Kiest de patiënt er voor om taken van een zorgaanbieder in te zien en te gebruiken vanaf een PGO, dan kan de DVP de persoon naar de aanbiedermodule-applicatie sturen met wat lichte context: “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.