Interfaces en use cases
Op deze pagina's staan de verantwoordelijkheden die horen bij de interfaces in het MedMij Afsprakenstelsel. In elke use case-implementatie wordt gebruik gemaakt van één of meer van deze interfaces. Onderstaande tabel laat zien welke use case-implementaties welk interface gebruiken.
| hoofdfunctie | Regie | Uitwisseling | Coördinatie | |||||||
|---|---|---|---|---|---|---|---|---|---|---|
| interface | user interface | authorization interface | token interface | subscription interface | subscription notification interface | resource notification interface | resource interface | GNL interface | OCL interface | ZAL interface |
| geboden door rol | Authorization Server | Subscription Server | Notification Server | Resource Server | MedMij Registratie | |||||
| UCI Verzamelen | X | X | X | X | ||||||
| UCI Delen | X | X | X | X | ||||||
| UCI Abonneren | X | X | X | X | ||||||
| UCI Notificeren | X | X | ||||||||
| UCI Opvragen GNL | X | |||||||||
| UCI Opvragen OCL | X | |||||||||
| UCI Opvragen ZAL | X | |||||||||
Verantwoordelijkheden over de adressering van deze interfaces komen hieronder aan de orde. Verantwoordelijkheden voor de specifieke interfaces zijn opgenomen in specifieke subpagina's, die klikbaar zijn in bovenstaande tabel.
Adressering
Adressen en interfaces
Op de zes interfaces in de flows van UCI Verzamelen, UCI Delen, UCI Abonneren en UCI Notificeren, adresseren Applicatie-rollen elkaar, op basis van een URI. Onderstaande tabel geeft een overzicht.
| hoofdfunctie | interface | geadresseerde | bericht | kanaal |
|---|---|---|---|---|
| Regie | authorization interface | Authorization Endpoint van de Authorization Server | authorization request | frontchannel |
OAuth Client (redirect_uri) | authorization response | |||
| token interface | Token Endpoint van de Authorization Server | access token request | backchannel | |
| subscription interface | Subscription Endpoint van de Subscription Server | subscription request | ||
| subscription notification interface | Subscription Notification Endpoint van de Notification Server | subscription notification | ||
| Uitwisseling | resource interface | Resource Endpoint van de Resource Server | resource request | |
| resource notification interface | Resource Notification Endpoint van de Notification Server | resource notification |
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, ook voor frontchannel en backchannel. Desondanks maken we in het logische informatiemodel, in de Zorgaanbiederslijst, wel onderscheid tussen Frontchanneluri en Backchanneluri. Dat houdt dat model wendbaarder, mocht er ooit wel adresseringsverschillen tussen frontchannel en backchannel ontstaan.
1a. De OAuth Client stelt conform RFC 3986 de URI samen waarmee hij zichzelf, de Authorization Server, de Subscription Server of de Resource Server adresseert. De Notification Client stelt conform RFC 3986 de URI samen waarmee hij de Notification Server adresseert.
1b. De URI's bedoeld in verantwoordelijk 1a hebben een hostname die een fully-qualified domain name is, conform RFC3696, sectie 2, en heeft het patroon scheme://host path, waarbij:
schemealtijdhttpsis, in lowercase;hosteen 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;
pathde syntax heeft vanpath-abemptyuit 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.
2a. In alle adressering op het authorization interface, het token interface, het subscription interface, het subscription notification interface, het resource notification interface en het resource interface is het gebruik van het voor https bedoelde poortnummer, zoals opgenomen in de Service Name and Transport Protocol Port Number Registry van IANA, verplicht.
Toelichting
Dat geldt dus ook voor de redirect_uri.
In release 1.1.1 van het MedMij Afsprakenstelsel was deze verantwoordelijkheid alleen van toepassing op frontchannel-verkeer en had de Dienstverlener Zorgaanbieder voor back-channelverkeer de vrijheid om een ander poortnummer te kiezen dan dat conform de IANA-lijst bij https hoort (443). Dat zorgt echter voor een extra beveiligingsbeheerlast bij de PGO Server die rekening houden met meerdere bestemmingspoortnummers bij uitgaand verkeer. Die beheerst brengt indirect ook extra beveiligingsrisico's met zich mee. Daartegenover staat dat de in deze release aangebrachte aanscherping naar verwachting geen wezenlijke beperking voor Dienstverleners Zorgaanbieder zal zijn, omdat zij toch al gebruik maken van het voor https bedoelde poortnummer uit de IANA-lijst. Een mogelijke uitzondering vormt de situatie waarin de Authorization Server en/of Resource Server in een multi-tenant omgeving draaien.
2b. Voor het samenstellen van alle adressen van het authorization request, het token request en het subscription request, betrekt de OAuth Client de eerste onderdelen van de URI, namelijk host en path, uit de Zorgaanbiederslijst, op basis van de van toepassing zijnde Zorgaanbieder, Interfaceversie en Gegevensdienst. Andere elementen van de algemene URI-syntax, zoals user, password, query en fragment, zijn afwezig in de adressen.
Voor het samenstellen van alle adressen van het resource request, betrekt de OAuth Client de base url (het onderdeel van de URI dat is aangeduid als [base] in de specificaties van de Transactie die behoort bij de van toepassing zijnde combinatie Zorgaanbieder, Gegevensdienst en Systeemrol), uit de Zorgaanbiederslijst, op basis van de van toepassing zijnde Zorgaanbieder, Interfaceversie, Gegevensdienst en Systeemrol. Wanneer de specificaties een request identificeren maar geen [base] aanduiden, mag de OAuth Client het resource request alleen indienen als de volledige, absolute URI van het resource request begint met de volledige ResourceEndpointuri zoals die is verkregen uit de Zorgaanbiederslijst, op basis van de van toepassing zijnde Zorgaanbieder, Interfaceversie, Gegevensdienst en Systeemrol.
2c. De adressen voor de subscription notification en de resource notification betrekt de Notification Client uit de OAuth Client List, op basis van de van toepassing zijnde OAuth Client en Gegevensdienst.
Zorgaanbiederslijst en OAuth Client List
De Zorgaanbiederslijst wordt dus gebruikt door de OAuth Client om, gegeven een zekere Interfaceversie, het endpoint te kennen dat past bij de van toepassing zijnde Zorgaanbieder, Gegevensdienst en, voor het resource endpoint, Systeemrol. Net zo gebruikt de Notification Client de OAuth Client List om, gegeven een zekere Interfaceversie, het endpoint te kennen dat past bij de van toepassing zijnde OAuth Client en Gegevensdienst. 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 in de Zorgaanbiederslijst, respectievelijk door de Dienstverlener persoon in de OAuth Client List.
3. MedMij Registratie wordt in UCI Opvragen ZAL, UCI Opvragen OCL en UCI Opvragen GNL geadresseerd met de hostname stelselnode.medmij.nl.