(MedMij Afsprakenstelsel 2.1.0B) Autoriseren
- Martin Wilmink
Inleiding
Er zijn twee vormen van autoriseren:
- Autorisatie zonder aanwezige geldige langdurige toestemming. Hierbij wordt gebruikgemaakt van de functie authenticatie.
- Autorisatie met aanwezige geldige langdurige toestemming. Hierbij wordt een geldig refreshtoken ingeruild voor een access-token en een nieuw refresh-token met een geldigheidsduur van een half jaar.
Hieronder worden beide manieren van autoriseren beschreven.
Businesslaag
Hieronder staan de diagrammen behorende bij de functie Autoriseren, zowel zonder als met geldige langdurige toestemming. De flow beschrijft alleen de situatie waarin alle acties slagen tot en met dat de Dienstverlener aanbieder geautoriseerd is (de zogenaamde happy flow). De oranje banen horen (conform de MedMij-huisstijl) tot het Persoonsdomein, de blauwe tot het Aanbiedersdomein en de grijze tot externe domeinen.
In de diagrammen en uitwerkingen wordt gesproken over toestemming. Dit heeft verschillende betekenissen:
- Bij de functies Verzamelen en Abonneren wordt hier de Toestemmingsverklaring afgegeven, waarmee de Dienstverlener aanbieder toestemming wordt gegeven gezondheidsgegevens naar de Dienstverlener persoon te zenden.
- Bij de functie Abonneren en Beheren toestemmingen kan ook een Beëindigingsverklaring worden afgegeven, waarmee de Persoon een abonnement stopt of de langdurige toestemming intrekt.
- Bij de functies Delen wordt hier de Bevestigingsverklaring afgegeven, waarmee de Dienstverlener aanbieder toestemming wordt gegeven gezondheidsgegevens van de Dienstverlener persoon te ontvangen.
Autoriseren zonder geldige langdurige toestemming
De totale procesgang van de functie Autoriseren zonder geldige langdurige toestemming is voor alle functies te gebruiken en kent de volgende stappen:
- De Dienstverlener aanbieder ontvangt een verzoek tot autorisatie.
- De Dienstverlener aanbieder presenteert de landingspagina
- De Dienstverlener aanbieder laat de Persoon zich authenticeren bij de Dienstverlener authenticatie.
- Nadat de persoon geauthenticeerd is, voert de Dienstverlener aanbieder optioneel de beschikbaarheidstoets of verplicht de ontvankelijkheidstoets uit en vraagt de Persoon om een toestemmings- of bevestigingsverklaring.
- De Dienstverlener aanbieder logt die toestemming en geeft een autorisatie af aan de Dienstverlener persoon.
Autoriseren met geldige langdurige toestemming
De totale procesgang van de functie Autoriseren met geldige langdurige toestemming is alleen voor de functie Verzamelen te gebruiken en kent de volgende stappen:
- De Dienstverlener aanbieder ontvangt een verzoek tot autorisatie.
De Dienstverlener aanbieder controleert het bewijs van langdurige toestemming en voert optioneel de beschikbaarheidstoets uit.
Als de beschikbaarheidstoets niet op dit moment uitgevoerd wordt, moet deze op de resource request plaatsvinden.
De Dienstverlener aanbieder geeft autorisatie af aan de Dienstverlener persoon.
Uitzonderingen op de Happy flow van de functie Autorisatie
In onderstaande tabel staan de uitzonderingssituaties beschreven. Alle uitzonderingssituaties worden door de Dienstverlener aanbieder ontdekt. Om te voorkomen dat de Dienstverlener persoon informatie over het bestaan van behandelrelaties verkrijgt zonder dat daarvoor (al) toestemming is gegeven, moet het onderscheid tussen de uitzonderingen 1 en 2 niet te maken zijn door de Dienstverlener persoon.
| nr. | uitzondering | actie | vervolg |
|---|---|---|---|
| autoriseren 1 | Dienstverlener aanbieder stelt op enig moment vast dat van Persoon bij Aanbieder geen gezondheidsinformatie voor die Gegevensdienst beschikbaar is. Zie de toelichting op Beschikbaarheids- en ontvankelijkheidsvoorwaarde. | Dienstverlener aanbieder informeert de Persoon dat diens verzoek geen voortgang kan vinden en noemt daarbij behorende reden. | Allen stoppen de flow onmiddellijk na geïnformeerd te zijn over de uitzondering. |
| autoriseren 2 | De voorgelegde Toestemmingsverklaring wordt niet afgegeven. | Dienstverlener aanbieder informeert DVP Server over deze uitzondering. DVP Server informeert Persoon dat diens verzoek geen voortgang kan vinden, maar laat de oorzaak daarvan helemaal in het midden. | |
| autoriseren 3 | Dienstverlener aanbieder kan het antwoord op de toestemmingsvraag niet vaststellen. | Dienstverlener aanbieder informeert Dienstverlener persoon over deze uitzondering. Dienstverlener persoon informeert daarop Persoon hierover. | Allen stoppen de flow onmiddellijk na geïnformeerd te zijn over de uitzondering. |
Applicatielaag
Autoriseren zonder geldige langdurige toestemming
Verantwoordelijkheden inzake uitzonderingen op de happy flow zijn opgenomen bij de respectievelijke interface, waar de uitzonderingen bij de functies zijn genoemd.
.png?version=1&modificationDate=1706606113549&cacheVersion=1&api=v2&width=437&height=400)
In elke voltrekking van de in het diagram beschreven flow is steeds sprake van één van elk van de bovenaan genoemde rollen.
De flow kent de volgende stappen:
- De User Agent stuurt een authorization request naar de Authorization Server.
De Authorization Server presenteert hierop de landingspagina aan de Persoon.
- Daarop begint de Authorization Server de OAuth-flow (in zijn rol als OAuth Authorization Server) door een sessie te creëren.
- Dan start de Authorization Server (nu in de rol van Authentication Client) de authenticatieflow.
- Na de authenticatieflow valideert de Authorization Server de identificerende gegevens en breekt het (vroegste) moment aan waarop of
- de Authorization Server ervoor instaat dat de Aanbieder voor de betreffende Gegevensdienst(en) überhaupt gezondheidsinformatie van die Persoon beschikbaar heeft, of anders de happy flow afbreekt. Op dit moment is de beschikbaarheidstoets optioneel voor de functie verzamelen, omdat later in het proces dezelfde toets verplicht uitgevoerd moet worden.
- de Authorization Server ervoor instaat dat voor de betreffende Gegevensdienst de Aanbieder ontvankelijk is voor de gezondheidsgegevens van de betreffende Persoon. Is dat zo, dan verstuurt de Authorization Server het access-token naar de DVP Server. Is dat niet zo, dan breekt de Authorization Server de happy flow af en stuurt zij geen access-token naar de DVP Server. Op dit moment is de ontvankelijkheidstoets verplicht.
- Indien de Aanbieder kan instaan voor de beschikbaarheid van tenminste één Gegevensdienst of kan instaan dat de Aanbieder voor de betreffende Gegevensdienst überhaupt gezondheidsinformatie van die Persoon wenst te ontvangen, dan presenteert de Authorization Server via de User Agent aan Persoon in een Toestemmingsverklaring, de vraag of Persoon de Aanbieder toestaat de gevraagde persoonlijke gezondheidsinformatie uit te wisselen met de DVP Server (als OAuth Client).
- Bij akkoord logt de Authorization Server dit als toestemming, genereert een authorization-code en stuurt dit als ophaalbewijs, door middel van een User Agent redirect met de in het authorization request ontvangen redirect_uri, naar de DVP Server. De Authorization Server stuurt daarbij de local state-informatie mee die hij in het authorization request van de DVP Server heeft gekregen. Laatstgenoemde herkent daaraan het verzoek waarmee hij de authorization-code moet associëren.
- De DVP Server vat niet alleen deze authorization-code op als ophaalbewijs, maar leidt er ook uit af dat de toestemming is gegeven en logt het verkrijgen van het ophaalbewijs.
- Met dit ophaalbewijs wendt de DVP Server zich weer tot de Authorization Server, maar nu zonder tussenkomst van de User Agent, voor een access-token.
- De Authorization Server valideert de authorization-code. Nu is het vroegste moment dat de verplichte beschikbaarheidstoets uitgevoerd kan worden. De andere optie is het uitvoeren van de beschikbaarheidstoets op het resource endpoint. Eén van deze twee momenten is verplicht.
- Daarop genereert de Authorization Server een access-token (en indien de Persoon langdurige toestemming geeft ook een referesh-token) en stuurt deze naar de DVP Server.
Autoriseren met geldige langdurige toestemming
Verantwoordelijkheden inzake uitzonderingen op de happy flow zijn opgenomen bij de respectievelijke interface, waar de uitzonderingen bij de functies zijn genoemd.
In elke voltrekking van de in het diagram beschreven flow is steeds sprake van één van elk van de bovenaan genoemde rollen.
De flow kent de volgende stappen:
- De User Agent stuurt een refresh-token naar de Authorization Server.
- Daarop begint de Authorization Server de OAuth-flow (in zijn rol als OAuth Authorization Server) door een sessie te creëren.
- Dan controleert de Authorization Server het refresh-token
- Hierna breekt het verplichte moment aan waarop of de Authorization Server ervoor instaat dat de Aanbieder voor de betreffende Gegevensdienst(en) überhaupt gezondheidsinformatie van die Persoon beschikbaar heeft, of anders de happy flow afbreekt. Zie ook de beschrijving over de beschikbaarheidstoets.
- Indien de Aanbieder kan instaan voor de beschikbaarheid van tenminste één Gegevensdienst, genereert de Authorization Server een access-token en een nieuw refresh-token en stuurt deze naar de DVP Server.