Page tree
Skip to end of metadata
Go to start of metadata


Toelichting

De UCI Verzamelen en UCI Delen zijn analoog van opzet. Voor de gegevens die omgaan in beide use case-implementaties betekent dat, dat zij grotendeels identiek zijn. Anticiperend op een even analoge evolutie in toekomstige releases van het MedMij afsprakenstelsel, zijn de verantwoordelijkheden over de gegevens en performance in beide use case-implementaties daarom in deze pagina bij elkaar geplaatst.

Toestemmingsverklaring en bevestigingsverklaring

1a. De vraag die aan de Zorggebruiker gesteld moet worden in de stap "autoriseer" in UCI Verzamelen staat gespecificeerd op de pagina Toestemmingsverklaring. Daarbij geldt dat:

  • de gebruikersvriendelijke weergave van de identiteit van de Zorgaanbieder (NaamZorgaanbieder) wordt bepaald door de betreffende Dienstverlener Zorgaanbieder, in haar dienstverleningsrelatie met de betreffende Zorgaanbieder;
  • de gebruikersvriendelijke weergave van de Gegevensdienst (NaamGegevensdienst) wordt betrokken uit de scope die de Authorization Server in de allereerste stap van de flow heeft gekregen, die overeenkomt met de Gegevensdienstnaam die bij de betreffende Gegevensdienst in de Gegevensdienstnamenlijst is opgenomen;
  • de gebruikersvriendelijke weergave van de identiteit van de Uitgever (NaamLeverancierPGO) wordt betrokken uit de OAuth Client List, op basis van de redirect_uri (van OAuth) die in stap 1 is verkregen.

1b. De vraag die aan de Zorggebruiker gesteld moet worden in de stap "bevestig" in UCI Delen staat gespecificeerd op de pagina Bevestigingsverklaring. Daarbij geldt dat:

  • de gebruikersvriendelijke weergave van de identiteit van de Zorgaanbieder (NaamZorgaanbieder) wordt bepaald door de betreffende Dienstverlener Zorgaanbieder, in haar dienstverleningsrelatie met de betreffende Zorgaanbieder;
  • de gebruikersvriendelijke weergave van de Gegevensdienst (NaamGegevensdienst) wordt betrokken uit de scope die de Authorization Server in de allereerste stap van de flow heeft gekregen, die overeenkomt met de Gegevensdienstnaam die bij de betreffende Gegevensdienst in de Gegevensdienstnamenlijst is opgenomen;
  • de gebruikersvriendelijke weergave van de identiteit van de Uitgever (NaamLeverancierPGO) wordt betrokken uit de OAuth Client List, op basis van de redirect_uri (van OAuth) die in stap 1 is verkregen.

Toelichting

NaamZorgaanbieder, NaamGegevensdienst en NaamLeverancierPGO zijn placeholders, zoals opgenomen in de Toestemmingsverklaring en de Bevestigingsverklaring.

Adressering en parameters

Toelichting

Op vier momenten in de flow van UCI Verzamelen, en die van UCI Delen, adresseren OAuth-rollen elkaar, op basis van een URI. Onderstaande tabel geeft een overzicht van die vier momenten. De adresbepaler is de OAuth-rol die de URI bepaalt (hier altijd de OAuth Client), de gebruiker de OAuth-rol die het bepaalde adres toepast. Wanneer de adresgebruiker de OAuth User Agent is, is de gebruiker dus niet de bepaler en verloopt het betreffende verkeer via de zogenoemde front-channel. In de andere twee gevallen is de OAuth Client bepaler en gebruiker en verloopt het verkeer via de zogenoemde back-channel.


gebruiksmomentadresbepaleradresgebruikergeadresseerdeparameters
authorization request (stap 1)OAuth Client (stap 1)OAuth User AgentAuthorization Endpoint van de OAuth Authorization Server
  • response_type
  • client_id
  • redirect_uri
  • scope
  • state
OAuth redirect (stap 10)OAuth Client (stap 1)OAuth User AgentOAuth Client
access token request (stap 12)OAuth Client (stap 12)OAuth ClientToken Endpoint van de OAuth Authorization Server
  • grant_type
  • code
  • geen client_id
  • redirect_uri
FHIR request (stap 14)OAuth Client (stap 14)OAuth ClientResource Endpoint van de OAuth Resource Server

In de nu volgende verantwoordelijkheden wordt bepaald hoe de URI's zijn opgebouwd waarmee de adresbepaler de adresgebruiker de geadresseerde laat adresseren, en hoe de parameters worden gevuld. De opbouw van het adres is steeds dezelfde, maar inzake poortnummers maken de verantwoordelijkheden een onderscheid tussen front- en back-channel.

2. De OAuth Client stelt conform RFC 3986 de URI samen waarmee hij zichzelf, de OAuth Authorization Server of de OAuth Resource Server adresseert. De URI heeft een hostname die een fully-qualified domain name is, conform RFC3696, sectie 2, en heeft het patroon scheme://host[:port] path, waarbij:

  • scheme altijd https is, in lowercase;
  • host een hostname is waarin
    • slechts de karakters [a-z][0-9], "." (punt) en "-" (koppelteken) voorkomen;
    • elke punt twee opeenvolgende segmenten scheidt en van elk der gescheiden segmenten geen deel uitmaakt;
    • het eerste karakter van een segment geen koppelteken is;
    • elk segment minstens één karakter lang is;
    • het laatste segment minstens twee karakters lang is;
    • het laatste karakter geen koppelteken mag zijn;
    • maximaal 255 tekens voorkomen;
    • ten minste twee segmenten voorkomen;
  • path de syntax heeft van path-abempty uit sectie 3.3 van RFC 3986 (en dus leeg mag zijn), maar niet eindigt op een /.

Toelichting

De eis dat https in lowercase staat volgt de canonical form zoals gespecificeerd in sectie 3.1 van RFC 3986. De eisen aan de hostname zijn o.a. gebaseerd op RFC 952 en RFC 1123. Het laatste segment is het zogeheten top-level domain.

3a. Ingeval de adresgebruiker OAuth User Agent is,

  • is het gebruik van het voor https bedoelde poortnummer verplicht dat is opgenomen in de Service Name and Transport Protocol Port Number Registry van IANA;
  • en, ingeval de geadresseerde het Authorization Endpoint van de OAuth Authorization Server is, betrekt de OAuth Client (als adres-bepaler) de URI, inclusief host en path, uit de Zorgaanbiederslijst, op basis van de van toepassing zijnde Zorgaanbieder en Gegevensdienst.

3b. Ingeval de adresgebruiker de OAuth Client is, betrekt de OAuth Client (als adres-bepaler) de eerste onderdelen van de URI, namelijk hostpath en eventueel port, uit de Zorgaanbiederslijst, op basis van de van toepassing zijnde Zorgaanbieder en hetzij Gegevensdienst (wanneer geadresseerde OAuth Authorization Server is) of Systeemrol (wanneer geadresseerde OAuth Resource Server is). Andere elementen van de algemene URI-syntax, zoals userpasswordquery en fragment, zijn afwezig in de adressen.

Toelichting

Met de eis dat host noch path op een / mag eindigen, wordt mogelijk gemaakt dat de URI, vooral in het vierde van de genoemde momenten, wordt aangevuld met informatiestandaard-specifieke URL-eindstukken, zonder dat de grens met het generieke MedMij-beginstuk onherkenbaar wordt.


De Zorgaanbiederslijst wordt dus gebruikt door de OAuth Client om het endpoint te kennen dat past bij de van toepassing zijnde Zorgaanbieder, Gegevensdienst en, voor het resource endpoint, Systeemrol. Daarom moet er uit één zo'n setje één endpoint-adres volgen. Andersom echter is dat geen eis. Het is mogelijk om, in elke door de Dienstverlener Zorgaanbieder gewenste combinatie, endpointadressen te hergebruiken voor meerdere van zulke setjes.

4. Voor één OAuth Authorization Server zijn de hostnames in de adressen voor zijn Authorization Endpoint en zijn Token Endpoint identiek.

Toelichting

Deze verantwoordelijkheid is opgenomen met het oog op de afbeelding, op de Netwerk-laag, van één Authorization Server op één ZA Node. Het Resource Endpoint mag wel met een andere hostname geadresseerd worden, omdat de Resource Server een andere rol is. Let wel, deze verantwoordelijkheid gaat enkel om de hostnames, niet om de gehele endpointadressen. Op andere elementen dan de hostname mogen de adressen van Authorization Endpoint en Token Endpoint wel verschillen.

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

parametervullingtoelichting

response_type

letterlijke waarde codeDit is het gevolg van verantwoordelijkheid 6 op de Applicatielaag.

client_id

dezelfde hostname van de OAuth Client die ook in de OAuth Clientlist is opgenomen

redirect_uri

zodanig dat de erin opgenomen hostname gelijk is aan de client_id en er geen poortnummer is opgenomenZie verantwoordelijkheid 3 hierboven.

scope

verplicht, met:

  • de betreffende (één) Zorgaanbiedernaam, ontdaan van de suffix @medmij, gevolgd door
  • een tilde (~), gevolgd door
  • het GegevensdienstId van de betreffende (één) Gegevensdienst uit de Gegevensdienstnamen.
De scope bestaat dus uit twee onderdelen, in een specifieke volgorde, gescheiden door een tilde. Er mag in de huidige 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.

state

conform sectie 4.1.1. van RFC 6749Hiermee 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.

6. 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.

 7. De parameters in de access token request worden als volgt gevuld:

parametervullingtoelichting

grant_type

letterlijke waarde authorization_codeDit is het gevolg van verantwoordelijkheid 6 op de Applicatielaag.

code

conform verantwoordelijkheid 11 op de ApplicatielaagZie de toelichting bij verantwoordelijkheid 11 op de Applicatielaag.

client_id

niet gebruiktDeze is niet nodig, want door verantwoordelijkheid 13 op de Applicatielaag wordt geborgd dat het access token alleen wordt verstrekt aan de OAuth Client aan wie de OAuth Resource Owner toestemming heeft verleend.

redirect_uri

dezelfde waarde als in de voorafgaande authorization request

8. In de resource request is de custom HTTP header medmijscope: opgenomen, met als waarde dezelfde scope als in de authorization request (zie verantwoordelijkheid 5).

Toelichting

Zo beschikt ook de Resource Server over de scope. Dit zorgt ervoor dat resource endpoint-adressen hergebruikt kunnen worden voor meerdere zorgaanbieders en geeft Resource Servers de mogelijkheid de toepasselijke Authorization Server te vinden ingeval Authorization Servers en Resource Server gescheiden geïmplementeerd zijn en één Resource Server met meerdere Authorization Servers van doen heeft.

Performance

9. Na ontvangst van een access token request, in UCI Verzamelen of UCI Delen, zal de Authorization Server, indien in antwoord daarop een access token dient te worden uitgegeven, na maximaal tien (10) seconden dit acces token ter beschikking stellen aan de PGO Server. Dit gedrag van de Authorization Server is gedurende minimaal 99,5% van de tijd beschikbaar.

10. Na ontvangst van een FHIR request, in UCI Verzamelen of UCI Delen, zal de Resource Server, indien in antwoord daarop een FHIR response dient te worden gedaan, na maximaal zestig (60) seconden dit FHIR response ter beschikking stellen aan de PGO Server. Dit gedrag van de Resource Server is gedurende minimaal 98,5% van de tijd beschikbaar.

  • No labels