Afsprakenset release 1.4.0 > Architectuur en technische specificaties > Applicatie > Interfaces > Authorization interface

Toelichting

Het authorization interface hoort bij de hoofdfunctie Regie.

Op deze pagina staan alleen de verantwoordelijkheden inzake het authorization interface die nog niet genoemd staan in de OAuth 2-specificatie.

1a. De parameters in de authorization request worden als volgt gevuld:

parameter	vulling	toelichting
`response_type`	letterlijke waarde `code`	Dit is het gevolg van verantwoordelijkheid 4 op de Applicatielaag.
`client_id`	de hostname, die in de OAuth Client List is opgenomen, van de Node van de OAuth Client die de authorization request doet
`redirect_uri`	zodanig dat de erin opgenomen hostname gelijk is aan de `client_id` en er geen poortnummer is opgenomen de `redirect_uri` moet volledig zijn en verwijzen naar een `https`-beschermd endpoint	Zie verantwoordelijkheden 1 en 2a op de pagina Interfaces. De tweede eis is een maatregel tegen beveiligingsrisico's 4.1.5, 4.2.4, 4.4.1.1, 4.4.1.5 en 4.4.1.6 in RFC 6819. Zie bovendien Token interface, de toelichting onder verantwoordelijkheid 4.
`scope`	optioneel: de letterlijke waarde `subscribe` gevolgd door een tilde `~` gevolgd door een niet-negatief geheel getal, aangevende de gevraagde maximale duur van het Abonnement gevolgd door een forward slash `/` gevolgd door, verplicht: de betreffende (één) Zorgaanbiedernaam, ontdaan van de suffix `@medmij`, gevolgd door een tilde (`~`), gevolgd door het GegevensdienstId van de betreffende (één) Gegevensdienst uit de Gegevensdienstnamenlijst.	De scope bestaat dus uit een optioneel deel gevolgd door twee verplichte onderdelen. Het optionele deel wordt gebruikt voor het aangaan, verlengen of beëindigen van een Abonnement. Als de gevraagde duur van het Abonnement `0` is, betekent dit dat het een verzoek betreft voor het beëindigen van het (mogelijk) geregistreerde Abonnement op die Gegevensdienst bij die Zorgaanbieder. De twee verplichte delen volgen op het eventuele optionele deel en bestaat zelf uit twee, gescheiden door een tilde. Er mag in deze versie van het MedMij Afsprakenstelsel slechts sprake zijn van één van elk. Bij interpretatie van de Zorgaanbiedernaam door de ontvanger zal deze de suffix `@medmij` weer moeten toevoegen. Er worden geen andere scopes of onderdelen van scopes opgenomen dan de hier genoemde. Voorbeelden van syntactisch juiste scopes zijn: `eenofanderezorgaanbieder~42`, voor het eenmalig afnemen van Gegevensdienst `42` bij `eenofanderezorgaanbieder@medmij`; `subscribe~180/eenofanderezorgaanbieder~42`, voor het aangaan van een Abonnement op Gegevensdienst `42` bij `eenofanderezorgaanbieder@medmij` van maximaal 180 dagen, of het aanpassen van het Abonnement op Gegevensdienst 42 bij `eenofanderezorgaanbieder@medmij` naar maximaal 180 dagen vanaf vandaag; `subscribe~0/eenofanderezorgaanbieder~42`, voor het beëindigen van het Abonnement op Gegevensdienst `42` bij `eenofanderezorgaanbieder@medmij`.
`state`	conform sectie 4.1.1. van RFC 6749 de waarde mag geen URI bevatten	Hiermee geeft de OAuth Client informatie mee aan de OAuth Authorization Server, waaraan eerstgenoemde later, bij de redirect, kan afleiden bij welk verzoek de authorization code hoort. Deze informatie is verder betekenisloos voor de OAuth Authorization Server. De tweede eis is een maatregel tegen beveiligingsrisico 4.1.5. De `state`-parameter mag niet bedoeld zijn om te worden toegevoegd aan, of anderszins verwerkt in de `redirect_uri`.

Afhandeling parameters

Conform de OAuth 2- specificatie moeten overige parameters die meegestuurd worden in het request genegeerd worden.

1b. De OAuth Client zorgt ervoor dat voor het authorization request de http-methode GET wordt gebruikt, niet POST.

Toelichting

In de OAuth-specificatie, sectie 3.1 wordt de Authorization Server verplicht gesteld GET te accepteren en wordt POST optioneel gehouden. Omdat GET de verreweg meest in het MedMij Afsprakenstelsel passende http-methode is voor de authorization request, geldt, om de Authorization Server niet voor onnodige implementatiekosten te plaatsen, deze verantwoordelijkheid. Hoewel deze verantwoordelijkheid een verantwoordelijkheid van de OAuth Client is, omdat deze onder de verantwoordelijkheid van een MedMij-deelnemer valt, wordt de request uiteindelijk door de OAuth User Agent uitgevoerd.

2a. Na ontvangst van een authorization request verifieert de Authorization Server dat:

de betreffende client_id voorkomt op de OAuth Client List;
de redirect_uri geldig is en voorkomt bij de betreffende client_id op de OAuth Client List.

Als een van deze verificaties niet slaagt dan behandelt de Authorization Server dit als uitzondering 1a volgens verantwoordelijkheid 6.

2b. Vervolgens verifieert de Authorization Server dat:

deze GegevensdienstId voorkomt bij de betreffende client_id op de OAuth Client List;
zij namens deze Zorgaanbieder deze Gegevensdienst ontsluit, in overeenstemming met de gepubliceerde Zorgaanbiederslijst;;
indien in de scope ook subscribe voorkomt:
- bij de betreffende client_id en Gegevensdienst op de OAuth Client List ook een subscription notification endpoint en een resource notification endpoint voorkomen;
- zij namens deze Zorgaanbieder ook Abonnementen op deze Gegevensdienst ontsluit;
de waarde van de duur parameter in het request de waarde heeft van 0 of een waarde groter dan 0 die kleiner of gelijk is aan de maximale duur van het Abonnement zoals de betreffende Zorgaanbieder deze aanbiedt.

Als een van deze verificaties niet slaagt dan behandelt de Authorization Server dit als uitzondering 1b volgens verantwoordelijkheid 6.

Verificatie van erkenning op Gegevensdienst

Zo voorkomt de Authorization Server dat gevolg wordt gegeven aan een verzoek dat blijkens de OAuth Client List of Zorgaanbiederslijst niet is toegestaan.

3. Tijdens de afhandeling van een authorization request laat de Authorization Server, in zijn rol als Authentication Client, voordat hij de Zorggebruiker om OAuth-autorisatie vraagt, de Zorggebruiker authenticeren door de Authentication Service.

Authenticatie

Conform stroomdiagram onder 1. De zorgaanbieder in het Zorgaanbieders- en dus BSN-domein is verplicht bij het verstrekken van gegevens vanuit een gezondheidsdossier de identiteit van de persoon te verifiëren aan de hand van het BSN.

Het MedMij Afsprakenstelsel brengt het gebruik van de Authentication Service onder in de OAuth-flow, onder operationele verantwoordelijkheid van de Authorization Server. Laatstgenoemde handelt in dezen onder verantwoordelijkheid van individuele Zorgaanbieders, want die zijn het waarvoor de Persoon zich authenticeert.

De directe interactie van de Persoon met de Authorization Server is bedoeld om de PGO Server te autoriseren om de Resource Server aan te spreken. Die levert de uiteindelijke Gegevensdienst pas.

4. Onmiddellijk na authenticatie van de Zorggebruiker, zoals bedoeld in verantwoordelijkheid 3, en alleen als deze slaagt, vraagt de OAuth Authorization Server de Zorggebruiker om een Toestemmingsverklaring (in het geval van UCI Verzamelen of UCI Abonneren) of een Bevestigingsverklaring (in het geval van UCI Delen), volgens het daaromtrent bepaalde op de pagina User interface (Autorisatieserver), volgens de standaard OAuth 2.0, op de wijze waarop deze in het MedMij Afsprakenstelsel wordt toegepast.

5. Voorafgaand aan uitgifte van een authorization code via de in de authorization request opgenomen redirect_uri, administreert de OAuth Authorization Server die authorization code en de daarvoor gebruikte redirect_uri.

Toelichting

Dit is een maatregel tegen beveiligingsrisico's 4.4.1.3, 4.4.1.5 en 4.4.1.7 uit RFC 6819 (zie Applicatie-laag, verantwoordelijkheid 18). Zie verantwoordelijkheid 4 bij het Token interface.

6. Authorization Server en PGO Server behandelen uitzonderingssituaties inzake het authorization interface af volgens onderstaande tabel.

Nummer	Implementeert uitzonderingen	Uitzondering	Actie	Melding	Vervolg
Authorization interface 1a	UC Verzamelen 1 UC Delen 1 UC Abonneren 1	Authorization Server ontvangt een authorization request zonder (geldige) `redirect_uri` en/of zonder een (geldige) `client_id`.	Authorization Server informeert PGO Presenter over deze uitzondering. Authorization Server voert geen redirect naar de Client uit, ook niet met een foutmelding.	conform OAuth 2.0-specificatie, par. 4.1.2.1	Allen stoppen de flow van de UCI Verzamelen/UCI Delen onmiddellijk na geïnformeerd te zijn over de uitzondering.
Authorization interface 1b	UC Verzamelen 1 UC Delen 1 UC Abonneren 1	Authorization Server ontvangt een ongeldige authorization request, anders dan uitzondering 1.	Authorization Server informeert PGO Server over deze uitzondering. PGO Server informeert Zorggebruiker daarover.	conform OAuth 2.0-specificatie, par. 4.1.2.1, met de daar genoemde, zo specifiek mogelijke, toepasselijke error code
Authorization interface 2	UC Verzamelen 2 UC Delen 2 UC Abonneren 2	Authorization Server kan de identiteit van de Zorggebruiker niet vaststellen.	Authorization Server informeert PGO Server over deze uitzondering. PGO Server informeert Zorggebruiker dat diens verzoek geen voortgang kan vinden, maar laat de oorzaak daarvan helemaal in het midden.	conform OAuth 2.0-specificatie, par. 4.1.2.1, error code `access denied`, met in de error description "`Access denied.`"
Authorization interface 3	UC Verzamelen 3 UC Delen 3 UC Abonneren 3	Authorization Server stelt tijdens de afhandeling van de authorization request vast dat: in geval van UCI Verzamelen: van Persoon bij Zorgaanbieder geen gezondheidsinformatie voor die Gegevensdienst beschikbaar is; in geval van UCI Delen: Zorgaanbieder niet ontvankelijk is voor die Gegevensdienst van Persoon; in geval van UCI Abonneren: Zorgaanbieder geen Notificaties beschikbaar maakt voor Persoon op die Gegevensdienst. Zie de toelichting op Beschikbaarheids- en ontvankelijkheidsvoorwaarde.
Authorization interface 4	UC Verzamelen 4 UC Delen 4 UC Abonneren 4	De autorisatievraag wordt ontkennend beantwoord.
Authorization interface 5	UC Verzamelen 5 UC Delen 5 UC Abonneren 5	Authorization Server kan de autorisatie niet vaststellen.	Authorization Server informeert PGO Server over deze uitzondering. PGO Server informeert daarop Zorggebruiker hierover.	conform OAuth 2.0-specificatie, par. 4.1.2.1, error code `access denied`, met in de error description "`Authorization failed.`"

Toelichting

De uitzonderingssituaties kunnen gezien worden als de implementatie-tegenhangers van de uitzonderingen van de UC Verzamelen en de UC Delen. Op de Applicatielaag zijn deze echter per interface geordend. Alle uitzonderingen worden door de Authorization Server ontdekt. In deze versie van het MedMij Afsprakenstelsel is bepaald dat zij altijd leiden tot het zo snel mogelijk afbreken van de flow door alle betrokken rollen. Daartoe moeten echter eerst nog de andere rollen geïnformeerd worden. Om te voorkomen dat de PGO Server informatie over het bestaan van behandelrelaties verkrijgt zonder dat daarvoor (al) toestemming is gegeven, moet het onderscheid tussen de uitzonderingen 2, 3 en 4 niet te maken zijn door de PGO Server.

Deze tabel bevat alleen die uitzonderingssituaties ten aanzien waarvan het MedMij afsprakenstelsel eigen eisen stelt aan de implementatie. In de specificatie van OAuth 2.0 staan daarnaast nog generiekere uitzonderingssituaties, zoals de situatie waarin de redirect URI ongeldig blijkt. Ook deze uitzonderingssituaties moeten geïmplementeerd worden.

Het authorization interface hoort bij de hoofdfunctie Regie.

Op deze pagina staan alleen de verantwoordelijkheden inzake het authorization interface die nog niet genoemd staan in de OAuth 2-specificatie.

1a.

De parameters in de authorization request worden als volgt gevuld:

parameter	vulling	toelichting
`response_type`	letterlijke waarde `code`	Dit is het gevolg van verantwoordelijkheid 4 op de Applicatielaag.
`client_id`	de hostname, die in de OAuth Client List is opgenomen, van de Node van de OAuth Client die de authorization request doet
`redirect_uri`	zodanig dat de erin opgenomen hostname gelijk is aan de `client_id` en er geen poortnummer is opgenomen de `redirect_uri` moet volledig zijn en verwijzen naar een `https`-beschermd endpoint	Zie verantwoordelijkheden 1 en 2a op de pagina Interfaces. De tweede eis is een maatregel tegen beveiligingsrisico's 4.1.5, 4.2.4, 4.4.1.1, 4.4.1.5 en 4.4.1.6 in RFC 6819. Zie bovendien Token interface, de toelichting onder verantwoordelijkheid 4.
`scope`	optioneel: de letterlijke waarde `subscribe` gevolgd door een tilde `~` gevolgd door een niet-negatief geheel getal, aangevende de gevraagde maximale duur van het Abonnement gevolgd door een forward slash `/` gevolgd door, verplicht: de betreffende (één) Zorgaanbiedernaam, ontdaan van de suffix `@medmij`, gevolgd door een tilde (`~`), gevolgd door het GegevensdienstId van de betreffende (één) Gegevensdienst uit de Gegevensdienstnamenlijst.	De scope bestaat dus uit een optioneel deel gevolgd door twee verplichte onderdelen. Het optionele deel wordt gebruikt voor het aangaan, verlengen of beëindigen van een Abonnement. Als de gevraagde duur van het Abonnement `0` is, betekent dit dat het een verzoek betreft voor het beëindigen van het (mogelijk) geregistreerde Abonnement op die Gegevensdienst bij die Zorgaanbieder. De twee verplichte delen volgen op het eventuele optionele deel en bestaat zelf uit twee, gescheiden door een tilde. Er mag in deze versie van het MedMij Afsprakenstelsel slechts sprake zijn van één van elk. Bij interpretatie van de Zorgaanbiedernaam door de ontvanger zal deze de suffix `@medmij` weer moeten toevoegen. Er worden geen andere scopes of onderdelen van scopes opgenomen dan de hier genoemde. Voorbeelden van syntactisch juiste scopes zijn: `eenofanderezorgaanbieder~42`, voor het eenmalig afnemen van Gegevensdienst `42` bij `eenofanderezorgaanbieder@medmij`; `subscribe~180/eenofanderezorgaanbieder~42`, voor het aangaan van een Abonnement op Gegevensdienst `42` bij `eenofanderezorgaanbieder@medmij` van maximaal 180 dagen, of het aanpassen van het Abonnement op Gegevensdienst 42 bij `eenofanderezorgaanbieder@medmij` naar maximaal 180 dagen vanaf vandaag; `subscribe~0/eenofanderezorgaanbieder~42`, voor het beëindigen van het Abonnement op Gegevensdienst `42` bij `eenofanderezorgaanbieder@medmij`.
`state`	conform sectie 4.1.1. van RFC 6749 de waarde mag geen URI bevatten	Hiermee geeft de OAuth Client informatie mee aan de OAuth Authorization Server, waaraan eerstgenoemde later, bij de redirect, kan afleiden bij welk verzoek de authorization code hoort. Deze informatie is verder betekenisloos voor de OAuth Authorization Server. De tweede eis is een maatregel tegen beveiligingsrisico 4.1.5. De `state`-parameter mag niet bedoeld zijn om te worden toegevoegd aan, of anderszins verwerkt in de `redirect_uri`.

Conform de OAuth 2- specificatie moeten overige parameters die meegestuurd worden in het request genegeerd worden.

1b.

De OAuth Client zorgt ervoor dat voor het authorization request de http-methode GET wordt gebruikt, niet POST.

Toelichting

In de OAuth-specificatie, sectie 3.1 wordt de Authorization Server verplicht gesteld GET te accepteren en wordt POST optioneel gehouden. Omdat GET de verreweg meest in het MedMij Afsprakenstelsel passende http-methode is voor de authorization request, geldt, om de Authorization Server niet voor onnodige implementatiekosten te plaatsen, deze verantwoordelijkheid. Hoewel deze verantwoordelijkheid een verantwoordelijkheid van de OAuth Client is, omdat deze onder de verantwoordelijkheid van een MedMij-deelnemer valt, wordt de request uiteindelijk door de OAuth User Agent uitgevoerd.

2a.

Na ontvangst van een authorization request verifieert de Authorization Server dat:

de betreffende client_id voorkomt op de OAuth Client List;
de redirect_uri geldig is en voorkomt bij de betreffende client_id op de OAuth Client List.

Als een van deze verificaties niet slaagt dan behandelt de Authorization Server dit als uitzondering 1a volgens verantwoordelijkheid 6.

2b.

Vervolgens verifieert de Authorization Server dat:

deze GegevensdienstId voorkomt bij de betreffende client_id op de OAuth Client List;
zij namens deze Zorgaanbieder deze Gegevensdienst ontsluit, in overeenstemming met de gepubliceerde Zorgaanbiederslijst;;
indien in de scope ook subscribe voorkomt:
- bij de betreffende client_id en Gegevensdienst op de OAuth Client List ook een subscription notification endpoint en een resource notification endpoint voorkomen;
- zij namens deze Zorgaanbieder ook Abonnementen op deze Gegevensdienst ontsluit;
de waarde van de duur parameter in het request de waarde heeft van 0 of een waarde groter dan 0 die kleiner of gelijk is aan de maximale duur van het Abonnement zoals de betreffende Zorgaanbieder deze aanbiedt.

Als een van deze verificaties niet slaagt dan behandelt de Authorization Server dit als uitzondering 1b volgens verantwoordelijkheid 6.

Toelichting

Zo voorkomt de Authorization Server dat gevolg wordt gegeven aan een verzoek dat blijkens de OAuth Client List of Zorgaanbiederslijst niet is toegestaan.

3.

Tijdens de afhandeling van een authorization request laat de Authorization Server, in zijn rol als Authentication Client, voordat hij de Zorggebruiker om OAuth-autorisatie vraagt, de Zorggebruiker authenticeren door de Authentication Service.

Toelichting

Conform stroomdiagram onder 1. De zorgaanbieder in het Zorgaanbieders- en dus BSN-domein is verplicht bij het verstrekken van gegevens vanuit een gezondheidsdossier de identiteit van de persoon te verifiëren aan de hand van het BSN.

Het MedMij Afsprakenstelsel brengt het gebruik van de Authentication Service onder in de OAuth-flow, onder operationele verantwoordelijkheid van de Authorization Server. Laatstgenoemde handelt in dezen onder verantwoordelijkheid van individuele Zorgaanbieders, want die zijn het waarvoor de Persoon zich authenticeert.

De directe interactie van de Persoon met de Authorization Server is bedoeld om de PGO Server te autoriseren om de Resource Server aan te spreken. Die levert de uiteindelijke Gegevensdienst pas.

4. Onmiddellijk na authenticatie van de Zorggebruiker, zoals bedoeld in verantwoordelijkheid 3, en alleen als deze slaagt, vraagt de OAuth Authorization Server de Zorggebruiker om een Toestemmingsverklaring (in het geval van UCI Verzamelen of UCI Abonneren) of een Bevestigingsverklaring (in het geval van UCI Delen), volgens het daaromtrent bepaalde op de pagina User interface (Autorisatieserver), volgens de standaard OAuth 2.0, op de wijze waarop deze in het MedMij Afsprakenstelsel wordt toegepast.

5.

Voorafgaand aan uitgifte van een authorization code via de in de authorization request opgenomen redirect_uri, administreert de OAuth Authorization Server die authorization code en de daarvoor gebruikte redirect_uri.

Toelichting

Dit is een maatregel tegen beveiligingsrisico's 4.4.1.3, 4.4.1.5 en 4.4.1.7 uit RFC 6819 (zie Applicatie-laag, verantwoordelijkheid 18). Zie verantwoordelijkheid 4 bij het Token interface.

6.

Authorization Server en PGO Server behandelen uitzonderingssituaties inzake het authorization interface af volgens onderstaande tabel.

Nummer	Implementeert uitzonderingen	Uitzondering	Actie	Melding	Vervolg
Authorization interface 1a	UC Verzamelen 1 UC Delen 1 UC Abonneren 1	Authorization Server ontvangt een authorization request zonder (geldige) `redirect_uri` en/of zonder een (geldige) `client_id`.	Authorization Server informeert PGO Presenter over deze uitzondering. Authorization Server voert geen redirect naar de Client uit, ook niet met een foutmelding.	conform OAuth 2.0-specificatie, par. 4.1.2.1	Allen stoppen de flow van de UCI Verzamelen/UCI Delen onmiddellijk na geïnformeerd te zijn over de uitzondering.
Authorization interface 1b	Authorization Server ontvangt een ongeldige authorization request, anders dan uitzondering 1.	Authorization Server informeert PGO Server over deze uitzondering. PGO Server informeert Zorggebruiker daarover.	conform OAuth 2.0-specificatie, par. 4.1.2.1, met de daar genoemde, zo specifiek mogelijke, toepasselijke error code
Authorization interface 2	UC Verzamelen 2 UC Delen 2 UC Abonneren 2	Authorization Server kan de identiteit van de Zorggebruiker niet vaststellen.	Authorization Server informeert PGO Server over deze uitzondering. PGO Server informeert Zorggebruiker dat diens verzoek geen voortgang kan vinden, maar laat de oorzaak daarvan helemaal in het midden.	conform OAuth 2.0-specificatie, par. 4.1.2.1, error code `access denied`, met in de error description "`Access denied.`"
Authorization interface 3	UC Verzamelen 3 UC Delen 3 UC Abonneren 3	Authorization Server stelt tijdens de afhandeling van de authorization request vast dat: in geval van UCI Verzamelen: van Persoon bij Zorgaanbieder geen gezondheidsinformatie voor die Gegevensdienst beschikbaar is; in geval van UCI Delen: Zorgaanbieder niet ontvankelijk is voor die Gegevensdienst van Persoon; in geval van UCI Abonneren: Zorgaanbieder geen Notificaties beschikbaar maakt voor Persoon op die Gegevensdienst. Zie de toelichting op Beschikbaarheids- en ontvankelijkheidsvoorwaarde.
Authorization interface 4	UC Verzamelen 4 UC Delen 4 UC Abonneren 4	De autorisatievraag wordt ontkennend beantwoord.
Authorization interface 5	UC Verzamelen 5 UC Delen 5 UC Abonneren 5	Authorization Server kan de autorisatie niet vaststellen.	Authorization Server informeert PGO Server over deze uitzondering. PGO Server informeert daarop Zorggebruiker hierover.	conform OAuth 2.0-specificatie, par. 4.1.2.1, error code `access denied`, met in de error description "`Authorization failed.`"

Toelichting

De uitzonderingssituaties kunnen gezien worden als de implementatie-tegenhangers van de uitzonderingen van de UC Verzamelen en de UC Delen. Op de Applicatielaag zijn deze echter per interface geordend. Alle uitzonderingen worden door de Authorization Server ontdekt. In deze versie van het MedMij Afsprakenstelsel is bepaald dat zij altijd leiden tot het zo snel mogelijk afbreken van de flow door alle betrokken rollen. Daartoe moeten echter eerst nog de andere rollen geïnformeerd worden. Om te voorkomen dat de PGO Server informatie over het bestaan van behandelrelaties verkrijgt zonder dat daarvoor (al) toestemming is gegeven, moet het onderscheid tussen de uitzonderingen 2, 3 en 4 niet te maken zijn door de PGO Server.

Deze tabel bevat alleen die uitzonderingssituaties ten aanzien waarvan het MedMij afsprakenstelsel eigen eisen stelt aan de implementatie. In de specificatie van OAuth 2.0 staan daarnaast nog generiekere uitzonderingssituaties, zoals de situatie waarin de redirect URI ongeldig blijkt. Ook deze uitzonderingssituaties moeten geïmplementeerd worden.