Token interface

Controle van door DVP ondersteunde gegevensdiensten bij uitgeven van access-tokens

Gewijzigde pagina’s:

Authorization interface
Token interface

Eerder werd op de authorization interface gecontroleerd of de gegevensdiensten die in de scope stonden ook op de OCL aanwezig waren. Doordat de gegevensdiensten niet langer worden opgenomen in de scope was het niet mogelijk deze te verifiëren aan de OCL. Met deze wijziging is deze verificatie verplichting uit de authorization interface gehaald en in andere vorm opgenomen in de 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 het 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 token request uitvoert. Deze moet hetzelfde zijn als de in het Authorization request gebruikte client_id.	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(!)

Het onderstaande voorbeeld dient als toelichting hoe het token request opgevuld zou moeten worden:

Token interface
TYPE REQUEST: POST 
https://authorization-server.com/token?grant_type=authorization_code
&code=jhgRtYbFpO12D3qR5tU9
&client_id= medmij.deenigeechtepgo.nl
&redirect_uri= https://medmij.deenigeechtepgo.nl
 
CUSTOM HEADERS:
X-Correlation-ID: c0e7b545-9606-4eef-bea7-75d8addaa54b
MedMij-Request-ID: 57510be1-73e6-4a75-9db8-ee005cced48f

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

core.tknint.200

3

De parameters in het 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
client_id	de hostname van de Node van de OAuth Client die de token request uitvoert. Deze moet hetzelfde zijn als de in het Authorization request gebruikte client_id.	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.

Het onderstaande voorbeeld dient als toelichting hoe het token request opgevuld zou moeten worden indien er gebruik wordt gemaakt van een refresh token:

Token interface
TYPE REQUEST: POST 
https://authorization-server.com/token?grant_type=refresh_token
&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA
&client_id= medmij.deenigeechtepgo.nl
 
CUSTOM HEADERS:
X-Correlation-ID: c0e7b545-9606-4eef-bea7-75d8addaa54b
MedMij-Request-ID: 57510be1-73e6-4a75-9db8-ee005cced48f

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

core.tknint.209

4

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 gegevensdienst aan voor desbetreffende Aanbieder. Omdat er hier sprake is van een acces token response bevat de scope de gegevendienstIDs. Dit is dus anders dan bij het authorization request, waarbij de zorgaanbieder in de scope staat. In de functie Verzamelen is er dus een verschil in de scope tussen het authorization request en het acces token response.

Het onderstaande voorbeeld dient als toelichting hoe het token response opgevuld zou moeten worden:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA",
  "scope": "51 52"
}

core.tknint.201

5

Voor het bepalen van de scope van het access-token verifieert de Authorization Server:

welke gegevensdiensten de Dienstverlener aanbieder namens deze Aanbieder ontsluit, in overeenstemming met de laatst gepubliceerde Aanbiederslijst;
voor welke door de Dienstverlener aanbieder ontsloten gegevensdienst de Dienstverlener persoon gekwalificeerd is, in overeenstemming met de laatst gepubliceerde OAuth Client List;
of de gegevensdiensten:
- betrekking hebben op de functie Verzamelen;
- de hostnames van de AuthorizationEndpoints, waarop de Gegevensdiensten worden aangeboden, met elkaar overeenkomen;
- de hostnames van de TokenEndpoints, waarop de Gegevensdiensten worden aangeboden, met elkaar overeenkomen.
of de Aanbieder daadwerkelijk gegevens beschikbaar heeft (beschikbaarheidstoets) voor de Persoon betreffende de gegevensdiensten.

Als een verificatie niet slaagt, wordt een gegevensdienst niet toegevoegd aan de scope van het access-token.

Toelichting

Voorbeeld:

De Dienstverlener aanbieder ontsluit namens de Aanbieder gegevensdiensten 31, 46, 50, 53, 58, 61, 62 en 65;
De Dienstverlener persoon is gekwalificeerd voor gegevensdiensten 46, 50, 53, 58, 61, 62 en 65;
Gegevensdienst 62 heeft betrekking op de functie Delen en valt af;
De hostnames voor gegevensdienst 65 wijken af, waardoor ook deze afvalt;
De Aanbieder heeft geen gegevens beschikbaar voor gegevensdienst 46, ook deze valt af.

Resultaat: scope = “50 53 58 61”

Door deze controles voorkomt de Authorization Server dat de scope van het access-token gegevensdiensten bevat die niet uitgewisseld kunnen of mogen worden.

core.tknint.210

6

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

7

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

core.tknint.203

8

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

9

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. Bij het inwisselen van een refresh token voor een access token wordt de parameter redirect_uri niet gebruikt.

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 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 Token interface wordt helemaal niet geredirect; die speelt zich geheel op het backchannel af.

core.tknint.205

10

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

11

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 Verzamelen en de 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