(v3.0.1) Token interface

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

1

De OAuth Client voegt bij het versturen van een Token request twee HTTP Header Fields toe, de eerste met de naam MedMij-Request-ID, de tweede met de naam X-Correlation-ID. Het MedMij-Request-ID moet een willekeurige waarde bevatten en dient uniek te zijn voor ieder request binnen het MedMij netwerk. De waarde bestaat uit een UUID. Het X-Correlation-ID heeft dezelfde waarde als het veld X-Correlation-ID dat bij het Authorization request is gebruikt, of indien gebruikgemaakt wordt van langdurige toestemming een nieuw unieke UUID.

core.tknint.208

2

De parameters in de request naar het token endpoint worden bij het gebruik van een authorization code (token request) als volgt gevuld:

parameter	vulling	toelichting
`grant_type`	conform verantwoordelijkheid core.autorisatie.205, core.autorisatie.206, core.autorisatie.207 en core.autorisatie.208	Dit is het gevolg van verantwoordelijkheid core.autorisatie.201.
`code`	conform verantwoordelijkheid core.autorisatie.205, core.autorisatie.206, core.autorisatie.207 en core.autorisatie.208	Zie de toelichting bij verantwoordelijkheid core.autorisatie.205, core.autorisatie.206, core.autorisatie.207 en core.autorisatie.208.
`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 de verantwoordelijkheden als beschreven in het hoofdstuk TLS en certificaten 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. De redirect_uri moet urlencoded zijn (conform RFC 3986).	NB: De redirect_uri MOET NIET dubbel encoded worden(!)

De parameters in de request naar het token endpoint worden bij het gebruik van een refresh token (refresh request) als volgt gevuld:

parameter	vulling	toelichting
grant_type	letterlijke waarde “refresh_token”	Conform hoofdstuk 6 van RFC6749
refresh_token	het uitgegeven refresh_token	Conform hoofdstuk 6 van RFC6749

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

core.tknint.200

3

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 core.autorisatie.204
`refresh_token`	Het hiermee uitgegeven refresh-token.	Conform verantwoordelijkheid core.autorisatie.211
`scope`	Conform sectie 5.1 van de OAuth 2.0-specificatie. 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.

core.tknint.201

4

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.

core.tknint.202

5

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

core.tknint.203

6

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 toelichting bij verantwoordelijkheden core.beveiliging.202, core.beveiliging.203, core.beveiliging.204). 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.

core.tknint.204

7

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 verantwoordelijkheid core.beveiliging.205).

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 (v3.0.1) 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 (v3.0.1) Authorization interface. Bij de afhandeling van het (v3.0.1) Token interface wordt helemaal niet geredirect; die speelt zich geheel op het backchannel af.

core.tknint.205

8

Na ontvangst van een access token request of een refresh request in de functie Verzamelen, zal de OAuth Authorization Server na maximaal tien (10) seconden dit acces token en refresh token ter beschikking stellen aan de OAuth Client. Bij het gebruik van een refresh request wordt het oude refresh-token ingetrokken en een nieuwe uitgegeven. Dit gedrag van de OAuth Authorization Server is gedurende minimaal 99,5% van de tijd beschikbaar.
Na ontvangst van een access token request, in de functie Delen, zal de OAuth Authorization Server 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.

core.tknint.206

9

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

Verzamelen 3

Delen 2

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

Authorization Server informeert DVP Server over deze uitzondering. DVP Server informeert daarop Persoon 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 functies (v3.0.1) Verzamelen en de (v3.0.1) 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.

core.tknint.207