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 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
Authorization: Bearer cGdvOnNlY3JldA...
Content-Type: application/x-www-form-urlencoded
POST https://dvauth/token
smart_launch_context = {
"resource": "Task/350755BC-E573-4004-91A3-91321E4BCA2A",
"intent": "startmodule",
"return_uri": "https://pgo/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
audience = dvamodule
scope = dvanaam
requested_token_type = medmij:token-type:one-time-code
200 OK
{
"access_token": "9c22a827e63e4139bcf3a03d7e787d71",
"expires_in": 60,
"token_type": "NA",
"scope": "scope",
"issued_token_type": "medmij:token-type:one-time-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"
}
3. Step-up afhandelen bij een invalid_grant
400 Bad Request
{
"error": "invalid_grant",
"error_description": "Step up: pas eerst gewone authorization code flow toe"
}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, |
audience |
Voorbeeld: dvamodule |
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, |
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.