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

Inleiding

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

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

parameter	vulling	toelichting
`grant_type`	letterlijke waarde "`authorization_code"`	Dit is het gevolg van verantwoordelijkheid 4 op de Applicatielaag.
`code`	conform verantwoordelijkheid 8a-d op de Applicatielaag	Zie de toelichting bij verantwoordelijkheid 8a-d op de Applicatielaag.
`client_id`	de hostname van de Node van de OAuth Client die de authorization request deed die de nu aangeboden authorization code opleverde	Het gebruik van client_id is verplicht. Conform het hoofdstuk 'Netwerk' moet al het netwerk-verkeer beveiligd worden met TLS. In hoofdstuk 2 van RFC8705 staat beschreven aan welke eisen voldaan moet worden bij een combinatie van OAuth2 en mutual TLS.
`redirect_uri`	dezelfde waarde als in de voorafgaande authorization request

Afhandeling parameters

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

2. De parameters in de access token response worden als volgt gevuld:

parameter	vulling	toelichting
`access_token`	Het hiermee uitgegeven access token.
`token_type`	letterlijke waarde `"Bearer"`
`expires_in`	900	Conform verantwoordelijkheid 7 op de Applicatie-laag.
`refresh_token`	niet gebruikt	Conform verantwoordelijkheid 7 op de Applicatie-laag.
`scope`	Conform sectie 5.1 van de OAuth 2.0-specificatie. In toevoeging daarop: verplicht indien het authorization request verzocht om een Abonnement. In dat geval is de `scope`-parameter gelijk aan die in de betreffende authorization request, maar met de Abonnements-einddatum gesteld op de door de Authorization Server toegekende, en dus mogelijk beperkte, waarde. De toegekende duur van het Abonnement is: niet hoger dan de in de authorization request gevraagde duur van het Abonnement; niet hoger dan de maximale abonnementsduur die de Zorgaanbieder in de Zorgaanbiederslijst had opgenomen bij die Gegevensdienst en die Interfaceversie; bij een gevraagde beëindiging gelijk aan `0`.

3a. De OAuth Client biedt een, via de in de authorization request opgenomen redirect_uri ontvangen authorization code, slechts aan de Authorization Server aan indien:

de waarde van de, in de authorization response ontvangen, state overeenkomt met de door de OAuth Client zelf gegenereerde state, die werd verzonden in het authorization request.

3b. De OAuth Client biedt een zekere authorization code maximaal eenmaal aan aan de Authorization Server.

3c. De Authorization Server voert een authorization code af, wanneer het eenmaal door een OAuth Client is aangeboden.

Toelichting

Dit is een maatregel tegen beveiligingsrisico 4.1.1 uit RFC 6819 (zie Applicatie-laag, toelichting bij verantwoordelijkheden 15-17). Het afvoeren van een authorization code houdt in dat de Authorization Server van een eenmaal uitgegeven authorization code bijhoudt of die al eens gebruikt is voor het verkrijgen van een access token. Mocht een authorization code voor een tweede of volgende keer worden aangeboden ter verkrijging van een access token, dan zal de Authorization Server dat weigeren en de flow afbreken. Als de Client aan wie die geweigerd wordt te kwader trouw was, is hiermee een gevaar afgewend. Was hij wel te goeder trouw en handelde hij conform het MedMij Afsprakenstelsel, dan was hij niet degene die al eerder dezelfde authorization code aanbood en blijkt er dus sprake geweest te zijn van een security breach.

4. De OAuth Authorization Server draagt geen access token over als in de token request geen redirect_uri is opgenomen, en evenmin als er in de token request wel een redirect_uri is opgenomen, maar deze niet identiek is aan de redirect_uri die de OAuth Authorization Server, bij uitreiking, verbonden heeft aan de authorization code die in de token request wordt aangeboden.

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

Met het oog op de parameters client_id en redirect_uri in de authorization request en de access token request geldt dat:

de client_id in de authorization request overeen moet komen met de hostname van de redirect_uri in diezelfde authorization request (verantwoordelijkheid 1 bij Authorization interface);
de redirect_uri in de access token request overeen moet komen met de redirect_uri in de authorization request (deze verantwoordelijkheid).

In de access token request speelt de redirect_uri dan niet de rol van adressering van de response, zoals in de authorization request wel, maar enkel als terugverwijzing naar de redirect_uri van het Authorization interface. Bij de afhandeling van het 134936345 wordt helemaal niet geredirect; die speelt zich geheel op het backchannel af.

5. Na ontvangst van een access token request, in UCI Verzamelen of UCI Delen, zal de OAuth 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 OAuth Client. Dit gedrag van de OAuth Authorization Server is gedurende minimaal 99,5% van de tijd beschikbaar.

6. OAuth Authorization Server en OAuth Client behandelen uitzonderingssituaties inzake het token interface volgens onderstaande tabel.

Nummer

Implementeert uitzondering

Uitzondering

Actie

Melding

Vervolg

Token interface 1

UC Verzamelen 6

UC Delen 6

UC Abonneren 6

Authorization Server moet vanwege één van de in de OAuth 2.0-specificatie, par. 5.2, genoemde redenen de token request weigeren.

Authorization Server informeert PGO Server over deze uitzondering. PGO Server informeert daarop Zorggebruiker hierover.

met de conform OAuth 2.0-specificatie, par. 5.2, toepasselijke error code

Allen stoppen de flow onmiddellijk na geïnformeerd te zijn over de uitzondering.

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.

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.

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

1.

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

parameter	vulling	toelichting
`grant_type`	conform verantwoordelijkheid 8a-d op de Applicatielaag	Dit is het gevolg van verantwoordelijkheid 4 op de Applicatielaag.
`code`	conform verantwoordelijkheid 8a-d op de Applicatielaag	Zie de toelichting bij verantwoordelijkheid 8a-d op de Applicatielaag.
`client_id`	de hostname van de Node van de OAuth Client die de authorization request deed die de nu aangeboden authorization code opleverde	Het gebruik van client_id is verplicht. Conform het hoofdstuk 'Netwerk' moet al het netwerk-verkeer beveiligd worden met TLS. In hoofdstuk 2 van RFC8705 staat beschreven aan welke eisen voldaan moet worden bij een combinatie van OAuth2 en mutual TLS.
`redirect_uri`	dezelfde waarde als in de voorafgaande authorization request

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

2.

De parameters in de access token response worden als volgt gevuld:

parameter	vulling	toelichting
`access_token`	Het hiermee uitgegeven access token.
`token_type`	letterlijke waarde `"Bearer"`
`expires_in`	900	Conform verantwoordelijkheid 7 op de Applicatie-laag.
`refresh_token`	niet gebruikt	Conform verantwoordelijkheid 7 op de Applicatie-laag.
`scope`	Conform sectie 5.1 van de OAuth 2.0-specificatie. In toevoeging daarop: verplicht indien het authorization request verzocht om een Abonnement. In dat geval is de `scope`-parameter gelijk aan die in de betreffende authorization request, maar met de Abonnements-einddatum gesteld op de door de Authorization Server toegekende, en dus mogelijk beperkte, waarde. De toegekende duur van het Abonnement is: niet hoger dan de in de authorization request gevraagde duur van het Abonnement; niet hoger dan de maximale abonnementsduur die de Zorgaanbieder in de Zorgaanbiederslijst had opgenomen bij die Gegevensdienst en die Interfaceversie; bij een gevraagde beëindiging gelijk aan `0`.

3a.

De OAuth Client biedt een, via de in de authorization request opgenomen redirect_uri ontvangen authorization code, slechts aan de Authorization Server aan indien:

de waarde van de, in de authorization response ontvangen, state overeenkomt met de door de OAuth Client zelf gegenereerde state, die werd verzonden in het authorization request.

3b. De OAuth Client biedt een zekere authorization code maximaal eenmaal aan aan de Authorization Server.

3c.

De Authorization Server voert een authorization code af, wanneer het eenmaal door een OAuth Client is aangeboden.

Toelichting

Dit is een maatregel tegen beveiligingsrisico 4.1.1 uit RFC 6819 (zie Applicatie-laag, toelichting bij verantwoordelijkheden 15-17). Het afvoeren van een authorization code houdt in dat de Authorization Server van een eenmaal uitgegeven authorization code bijhoudt of die al eens gebruikt is voor het verkrijgen van een access token. Mocht een authorization code voor een tweede of volgende keer worden aangeboden ter verkrijging van een access token, dan zal de Authorization Server dat weigeren en de flow afbreken. Als de Client aan wie die geweigerd wordt te kwader trouw was, is hiermee een gevaar afgewend. Was hij wel te goeder trouw en handelde hij conform het MedMij Afsprakenstelsel, dan was hij niet degene die al eerder dezelfde authorization code aanbood en blijkt er dus sprake geweest te zijn van een security breach.

4.

De OAuth Authorization Server draagt geen access token over als in de token request geen redirect_uri is opgenomen, en evenmin als er in de token request wel een redirect_uri is opgenomen, maar deze niet identiek is aan de redirect_uri die de OAuth Authorization Server, bij uitreiking, verbonden heeft aan de authorization code die in de token request wordt aangeboden.

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

Met het oog op de parameters client_id en redirect_uri in de authorization request en de access token request geldt dat:

de client_id in de authorization request overeen moet komen met de hostname van de redirect_uri in diezelfde authorization request (verantwoordelijkheid 1 bij Authorization interface);
de redirect_uri in de access token request overeen moet komen met de redirect_uri in de authorization request (deze verantwoordelijkheid).

In de access token request speelt de redirect_uri dan niet de rol van adressering van de response, zoals in de authorization request wel, maar enkel als terugverwijzing naar de redirect_uri van het Authorization interface. Bij de afhandeling van het 134936345 wordt helemaal niet geredirect; die speelt zich geheel op het backchannel af.

5.

Na ontvangst van een access token request, in UCI Verzamelen of UCI Delen, zal de OAuth 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 OAuth Client. Dit gedrag van de OAuth Authorization Server is gedurende minimaal 99,5% van de tijd beschikbaar.

6.

OAuth Authorization Server en OAuth Client behandelen uitzonderingssituaties inzake het token interface volgens onderstaande tabel.

Nummer

Implementeert uitzondering

Uitzondering

Actie

Melding

Vervolg

Token interface 1

UC Verzamelen 6

UC Delen 6

UC Abonneren 6

Authorization Server moet vanwege één van de in de OAuth 2.0-specificatie, par. 5.2, genoemde redenen de token request weigeren.

Authorization Server informeert PGO Server over deze uitzondering. PGO Server informeert daarop Zorggebruiker hierover.

met de conform OAuth 2.0-specificatie, par. 5.2, toepasselijke error code

Allen stoppen de flow onmiddellijk na geïnformeerd te zijn over de uitzondering.

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.

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.