MMOS-68 Onjuiste scope beschrijving op Authorization interface

Probleem: Op https://afsprakenstelsel.medmij.nl/display/MMOptioneel/Authorization+interface staat nog beschreven dat de scope bestaat uit aanbieder-gegevensdienst-combinaties. Dat klopt niet, zoals in core.autorisatie.203 te vinden is.

Change classificatie => Patch of Minor ?

Deze change betreft het in lijn brengen van de tekst beschreven in Autorisatie interface met de functionele beschrijving 'Verzamelen' waarbij de scope van het verzamelen autorisatie verzoek beperkt is tot de MedMij-aanbieder naam. En een correctie op verantwoordelijkheden autorisatie voor delen (oorspronkelijk tekst teruggeplaatst).

Dit betreffen correcties van de bestaande teksten en geen toevoeging/wijziging van de in 2.0.0 geïntroduceerde functionaliteit mbt langdurige/eenmalige toestemming.

Deze argumentatie lijn volgend kun je deze change classificeren als Patch. (initieel idee)

Bekijkend vanuit technische impact:

Het wijzigen van de Scope heeft een impact op de implementatie van de autorisatie flow. Met deze correctie/aanpassing veranderd de scoop-waarde en is er een impact op de uitwisseling. Bij het ontbreken van ~gegevensdienst-id wordt in de huidige implementatie (1.6) het bericht afgekeurd, in de nieuwe situatie is dit wel toegestaan, maw is deze aanpassing dan Forward-compatibel?

Bij Forward-compatibel zijn is deze change te classificeren als Minor.
(Dit los van de functioneel juist beschreven functie tav de autorisatie flow.)

Ik, Casper, voer dit door als Patch. De reden hiertoe is dat dit een inconsistentie betreft met een wel aangepast deel van het afsprakenstelsel. Ook dit had al in de Major (2.0.0) meegenomen moeten worden. Daarom is dit ten opzichte van 2.0.0 geen impact, die impact zat al bij de major-release. Deze wijziging is ter verduidelijking en verbetering van het afsprakenstelsel en zorgt op zichzelf niet voor een probleem in backwards compatibility.

Huidige tekst

Nieuwe tekst voor kopje scope

scope

Voor "verzamelen":

MedMij-naam van de Aanbieder

Voor "delen":

één aanbieder-gegevensdienst-combinatie.

Een aanbieder-gegevensdienst-combinatie bestaat uit:

één Aanbiedernaam, ontdaan van de suffix @medmij
gevolgd door een tilde (~)
gevolgd door één GegevensdienstId van een Gegevensdienst uit de Gegevensdienstnamenlijst.

Er worden geen andere scopes of onderdelen van scopes opgenomen dan de genoemde.

Voorbeelden van syntactisch juiste scopes zijn:

Verzamelen:

"eenofanderezorgaanbieder", voor het uitwisselen van gegevens met eenofanderezorgaanbieder@medmij;

"eenofanderezorgaanbieder~53", voor het eenmalig afnemen van Gegevensdienst 53 bij eenofanderezorgaanbieder@medmij;
"eenofanderezorgaanbieder~53 eenofanderezorgaanbieder~57, voor het eenmalig afnemen van Gegevensdiensten 53 en 57 bij eenofanderezorgaanbieder@medmij.

Vraag @Casper van der Harst : Ron komt met de opmerking dat als we de gegevensdiensten gaan loslaten (op den duur ook bij delen) hoe weet je dan dat het om request voor verzamelen of delen is. Misschien een idee om een ~ verzamlen en een ~ delen nu al mee op te nemen in de scope. Nu dan bij verzamelen en als we delen gaan aanpassen bij delen?

Antwoord Casper: Dit ga ik nu op het laatste moment niet doorvoeren. Eventueel kan dit later besproken worden. Bijvoorbeeld zodra we dit ook gaan doorvoeren voor delen.

Vraag aan @Casper van der Harst :

We hebben voor verzamelen gezegd dat we de gegevensdiensten loslaten. Aan delen hebben we niets veranderd, daar staat nog steeds dat de User Agent van de Persoon de mogelijkheid presenteert om een bepaalde Gegevensdienst met een zekere Aanbieder te delen. Het gaat altijd om precies één Gegevensdienst (één scope, in OAuth-termen). Zowel bij delen als verzamelen verwijzen we naar dezelfde verantwoordelijkheden:

Hoewel het technisch mogelijk is om meerdere scopes mee te geven, maakt de OAuth Client gebruik van één scope tegelijk. Hierin staat de MedMij-naam van de Aanbieder, waarbij autorisatie wordt gevraagd, genoemd. De OAuth Authorization Server genereert authorization-codes en access-tokens met een enkelvoudige scope die gelijk is aan de scope in het verzoek van de OAuth client.

core.autorisatie.203

Moeten we dan niet een aparte verantwoordelijkheid opnemen specifiek voor delen (zoals ook in 1.6.0) en bij de andere aangeven dat dit voor verzamelen geldt?

zie voorstel voor AS hieronder

Nieuwe tekst voor https://afsprakenstelsel.medmij.nl/display/MMOptioneel/Verantwoordelijkheden%2C+Core kopje autorisatie en dan regel 6 (core.autorisatie.203)

Hoewel het technisch mogelijk is om meerdere scopes mee te geven, maakt de OAuth Client voor de functie Verzamelen gebruik van één scope tegelijk. Hierin staat de MedMij-naam van de Aanbieder, waarbij autorisatie wordt gevraagd, genoemd. De OAuth Authorization Server genereert authorization-codes en access-tokens met een enkelvoudige scope die gelijk is aan de scope in het verzoek van de OAuth client.

Voor de functie delen geldt dat dee OAuth Client alleen gebruikmaakt van één scope tegelijk. De OAuth Authorization Server genereert authorization-codes en access-tokens met een enkelvoudige scope die geheel vervat moet zijn in de Gegevensdienst waarom de OAuth Client heeft gevraagd.

Toelichting >

Bij het genereren van codes en tokens voor de functie Delen is de OAuth-scope meegenomen. Deze is gerelateerd aan de Gegevensdienst. Hoewel het technisch mogelijk is om meerdere scopes mee te geven is de scope beperkt tot één Gegevensdienst per keer.

core.autorisatie.203

Aanpassing tekst op https://afsprakenstelsel.medmij.nl/display/MMOptioneel/Verzamelen bullet 2 onder applicatie laag:

De rode doorgehaalde tekst verwijderen

De Persoon maakt expliciet zijn selectie van Aanbieder en laat de User Agent een authorization request sturen naar de Authorization Server. Het adres van het authorization endpoint komt uit de Aanbiederslijst. De redirect_uri geeft aan waarnaartoe de Authorization Server de User Agentverderop moet redirecten (met de authorization-code). Het authorization request mag desgewenst, onder voorwaarden, meerdere Gegevensdiensten van de Aanbieder bevatten. Binnen het autorisatieproces valt ook het eerst mogelijke moment waarop de Dienstverlener aanbieder moet instaan dat voor de Gegevensdienst waartoe een verzoek behoort de Aanbieder de gezondheidsgegevens beschikbaar heeft.

NIEUWe CORRECTIES: STAAT NOG NIET KLAAR:

oude tekst:

Nieuwe tekst:

Regel over scope weghalen!

Scope - In toevoeging daarop: verplicht voor de functie Verzamelen. De scope bevat de gegevensdiensten (nummers) die op het moment van uitgeven van het access-token voldoen aan de volgende voorwaarden:

De DVA is gekwalificeerd voor de gegevensdienst.
De DVA biedt de gegevensdient aan voor desbetreffende Aanbieder.

Oud plaatje in

Vervangen door

op staat:

De flow kent de volgende stappen:

de User Agent stuurt een authorization request naar de Authorization Server. Het adres van het authorization endpoint komt uit de Aanbiederslijst. De redirect_uri geeft aan waarnaartoe de Authorization Server de User Agent verderop moet redirecten (met de authorization code). Het authorization request mag desgewenst, onder voorwaarden, meerdere Gegevensdiensten van de Aanbieder bevatten.

Toestemming voor meerdere Gegevensdiensten van een Aanbieder
In een authorization request mogen meerdere Gegevensdiensten van eenzelfde Aanbieder worden gecombineerd wanneer:
1. de gegevensdiensten worden aangeboden binnen één zelfde interfaceversie, EN
2. de FQDN van de in de ZAL, voor deze gegevensdiensten, opgenomen AuthorizationEndpoints met elkaar overeenkomen, EN
3. de FQDN van de in de ZAL, voor deze gegevensdiensten, opgenomen TokenEndpoints met elkaar overeenkomen.

Rode doorgehaalde tekst moet weg, in het authorization request stuur je geen scope meer mee

verantwoordelijkheden - authorization interface

er staat:

Moet de gegevensdiensttoets uit het authorization request en dus verhuizen?

Vervolgens verifieert de Authorization Server dat:

bij de functie Verzamelen:
- zij namens deze Aanbieder, voor de gehanteerde Interfaceversie, Gegevensdienst(en) ontsluit, in overeenstemming met de gepubliceerde Aanbiederslijst;
bij de functie Delen:
- alle gevraagde GegevensdienstId's voorkomen op de OAuth Client List, bij de betreffende client_id en voor de gehanteerde Interfaceversie;
- indien in de scope meerdere GegevensdienstId's zijn opgenomen:
  - alle Gegevensdiensten betrekking hebben op de functie Delen;
  - de hostnames van de AuthorizationEndpoints, waarop de Gegevensdiensten worden aangeboden, met elkaar overeenkomen;
  - de hostnames van de TokenEndpoints, waarop de Gegevensdiensten worden aangeboden, met elkaar overeenkomen.

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