Document toolboxDocument toolbox

Vervallen op 14 mei 2022

Interfaces

Owned by Former user (Deleted)
Last updated: Apr 19, 2021 by Casper van der HarstVersion comment
4 min read

Inleiding

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.

hoofdfunctieRegieUitwisselingCoördinatie
interfaceuser interfaceauthorization interfacetoken interfacesubscription interfacesubscription
notification interface		resource
notification interface		resource interfaceGNL interfaceOCL interfaceZAL interface
geboden door rolAuthorization
Server		Subscription
Server		Notification
Server		Resource
Server		MedMij
Registratie
UCI VerzamelenXXX


X


UCI DelenXXX


X


UCI AbonnerenXXXX





UCI Notificeren



XX



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.

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.

hoofdfunctieinterface

geadresseerde

bericht

kanaal

Regieauthorization interfaceAuthorization Endpoint
van de Authorization Server		authorization requestfrontchannel
OAuth Client (redirect_uri)authorization response
token interfaceToken Endpoint 
van de Authorization Server		access token requestbackchannel


subscription interfaceSubscription Endpoint
van de Subscription Server		subscription request
subscription notification interfaceSubscription Notification Endpoint
van de Notification Server		subscription notification
Uitwisselingresource interfaceResource Endpoint 
van de Resource Server		resource request
resource notification interfaceResource 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.

Adressering

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:
  • 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.

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.
3.MedMij Registratie wordt in UCI Opvragen ZAL, UCI Opvragen OCL en UCI Opvragen GNL geadresseerd met de hostname stelselnode.medmij.nl.
 Toelichting

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.

Vervallen op 14 mei 2022