Beschrijving

In koppeltaal staat de FHIR resource service centraal. Applicaties, en niet personen, hebben toegang tot deze FHIR resource service. Zoals in het onderdeel Applicatierollen en rechten (TODO, link) beschreven, heeft elke applicatie een rol, die op zijn beurt gekoppeld zijn aan rechten. Om applicaties toegang te geven tot de FHIR resource service dient deze eerst geauthenticeerd te worden. Het proces van vaststellen of de applicatie is wie die zegt dat hij is. Daarna vindt autorisatie plaats, vaststellen of de applicatie de rechten heeft de vraag of opdracht uit te voeren. Dit onderdeel heeft enkel betrekking op de authenticiteit van de applicatie. De autorisatie gebeurt door middel van de rollen en rechten beschreven in Applicatierollen en rechten (TODO, link).

De authenticatie van de applicatie wordt gerealiseerd door middel van het SMART on FHIR backend services protocol. Dit protocol is gebaseerd op OAuth2 client credential flow. Deze SMART on FHIR backend services maakt gebruik van JWT gebaseerde client credentials (rfc7523). Deze vorm van authenticatie gaat uit van een manier van authenticeren gebaseerd op een publieke / private key combinatie.

Overwegingen

SMART on FHIR backend services

In koppeltaal krijgen niet personen maar applicaties toegang tot de FHIR resource service. In het koppeltaal domein wordt door middel van rollen vastgelegd welke rechten een applicatie heeft. De SMART on FHIR backend services beschrijft hoe een applicatie toegang krijgt tot de FHIR resource service, en vervult hiermee een groot deel van het toegang krijgen. Waar koppeltaal meer specifiek wordt dan SMART on FHIR backend services is op het gebied van de rechten die de applicatie krijgt. Deze worden vastgelegd in het access_token door middel van door Koppeltaal beschreven autorisatieregels, zodat er een koppelvlak ontstaat tussen autorisatie service en FHIR resource service.

JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication (rfc7523)

In eerdere versies van koppeltaal worden de credentials door middel van een client_id en een geheime sleutel gerealiseerd. In SMART on FHIR backend services wordt gebruik gemaakt van JWT Profile for OAuth 2.0 Client Authentication rfc7523. In dit profiel wordt een JWT token als bewijs van de client authenticatie (client assertion) meegegeven. De authenticatie gebeurt niet op basis van een gedeeld geheim, maar op de ondertekening van een bericht met een asymmetrische sleutelpaar. Dit sleutelpaar wordt door de cliënt gegenereerd. Het sleutelpaar bestaat uit twee delen; een geheim deel en een publiek deel. Een dergelijk sleutelpaar wordt een public / private key genoemd. De publieke sleutel kan enkel gebruikt worden om een ondertekend JWT token mee te controleren, enkel de geheime sleutel kan gebruikt worden om het JWT token te ondertekenen. Dit heeft een aantal grote voordelen ten opzichte van een gedeeld geheim. In het geval van een gedeeld geheim moet het geheim altijd gedeeld worden, met het risico van mogelijk verlies van het geheim. In sleutelpaar kan gemakkelijk gegenereerd worden en het geheime deel hoeft nooit de omgeving te verlaten. Het is mogelijk meerdere actieve sleutelparen te hebben, zodat indien een omgeving uit meerdere instanties bestaat, iedere instantie een eigen sleutelpaar kan genereren. Omdat bij de publicatie van de publieke sleutels gebruik gemaakt wordt van JWKS (TODO, link invoegen), kunnen sleutels gemakkelijk en snel vernieuwd worden.

Het access_token

Het access_token bestaat is een JWT token. Hoe dit access_token er uit ziet ligt vast in koppeltaal. Door in het het access_token de toegangsegels van de applicatie die het token aanvraagt vast te leggen, ontstaat een ontkoppeling tussen FHIR resource service en de autorisatie service. De gegevens die nodig zijn om toegang te verlenen liggen vast in het access_token en hoeven niet verder uitgewisseld te worden. Een willekeurige FHIR service kan, indien deze de autorisatie service vertrouwt, de inhoud van het token direct vertalen naar toepasbare restricties. Deze restricties worden vastgelegd in de scope van het JWT token. De syntax die voor deze scope wordt gebruikt is de SMART Scopes syntax. In koppeltaal wordt enkel gebruik gemaakt van System-level scopes, omdat de toegang wordt verstrekt aan applicaties. De formattering van deze syntax wordt bij de toepassing toegelicht.

De scope in het token request

Omdat de applicaties in het koppeltaaldomein toegewezen rollen hebben, die naar permissies vertaald worden en in het scope veld het access_token worden vastgelegd als autorisatieregels, is de scope in de aanvraag voor een token voor een applicatie van weinig belang; de waarde wordt gevuld met de rol die het domein de applicatie heeft toegekend. Om deze reden is het toegestaan de waarde * te gebruiken voor het verkrijgen van alle toegestane permissies in de aangevraagde scope. Indien de applicatie om enkel een specifieke scope vraagt, mag de autorisatie service de uitgegeven scope hiermee beperken.

Relatie client_id en device reference

In koppeltaal wordt de client_id gelijk gesteld aan de logical id van de Device resource van deze applicatie. Deze identifier die in veel gevallen door de FHIR resource service wordt toegekend. Deze waarde wordt ook als identifier van het systeem https://simplifier.net/koppeltaalv2.0/koppeltaal-clientid in het Device opgeslagen. De reden voor deze aanpak is dat het op deze manier mogelijk wordt om van Device reference naar client_id te kunnen vertalen zonder toegang tot de Device resources nodig te hebben. De relatie client_id en Device is dus dat praktisch gezien de device referentie altijd Device/<client_id> is.

Toepassing, restricties en eisen

SMART on FHIR backend services toegelicht

De SMART on FHIR backend service is gebaseerd op uit een OAuth 2 client authentication flow met als methode voor client authentication rfc7523, bestaande uit een JWT bearer token in de HTTP Authorization header. Deze standaard wordt beschreven in de bestaande documentatie. De OAuth 2 client authentication flow bestaat uit een enkel request naar de authorization service waar op basis van de identiteit van de cliënt een access_token wordt toegekend. Er wordt door SMART on FHIR backend services geen gebruik gemaakt van een refresh_token, dit is gebruikelijk bij de OAuth 2 client authentication flow, omdat de access_token eenvoudig en geautomatiseerd opnieuw aangevraagd kan worden. Koppeltaal bepaald verder dat de levensspanne van het access_token kort is, dit om wijzigingen in rechten en permissies snel te kunnen propageren. Hoe de client zich authenticeert wordt in het volgende onderdeel besproken.

De aanvraag, het antwoord, en het access token token.

De aanvraag van de applicatie naar de autorisatie service gebeurt door een POST request met de volgende parameters met de application/x-www-form-urlencoded encoding:

scope: een lijst van scopes volgens het permissie schema of * voor alle beschikbare permissies. Om verwarring te voorkomen, er staat ook een scope in het access token.
grant_type: altijd client_credentials
client_assertion_type: altijd urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertion: het gegenereerd JWT token van de applicatie. Deze wordt in het onderdeel JWT Profile for OAuth 2.0 Client Authentication (rfc7523) verder toegelicht.

Het antwoord kent de volgende velden:

access_token, de JWT die gebruikt kan worden om de FHIR resource server mee te benaderen.
token_type: altijd ‘bearer’
expires_in: de tijdspanne van het token, maximaal 5 minuten. Deze komt overeen met het Issued At (iat) veld van de JWT access_token.
scope: de toegewezen permissies, deze zijn identiek aan de waarde van het scope veld van het JWT access_token. Deze wordt in het onderdeel Het access_token en de SMART Scopes syntax verder toegelicht.

De REST API van de FHIR Resource service kan met het access_token benaderd worden. Dit kan maximaal binnen de tijdspanne van de expires_in waarde. Indien het token verlopen is, moet er een nieuw token aangevraagd worden. Het access token wordt meegegeven in de HTTP Authorization header, en wordt voorafgegaan met de waarde Bearer.

JWT Profile for OAuth 2.0 Client Authentication (rfc7523)

Dit profiel boven op OAuth 2 bepaalt dat de cliënt, de applicatie in het geval van koppeltaal, zich identificeert met client credentials in de vorm van een ondertekend JWT token. Dit doet de applicatie door een JWT token te ondertekenen met zijn eigen gegenereerde sleutelpaar. Het ondertekende JWT token bevat als issuer (iss) veld de client_id van de applicatie. De autorisatie server moet het token valideren door middel van de publieke sleutel die is gekoppeld aan de cliënt. Deze publieke sleutel wordt door middel van een JWKS url beschikbaar gesteld. De velden in het JWT token zijn als volgt gemapped:

iss: de client_id van de applicatie
sub: de client_id van de applicatie
aud: de URL van het token_endpoint
iat: timestamp van uitgifte
jti: unieke waarde per token
exp: geldig tot timestamp, maximaal 5 minuten

De header van het client credential token moet de key id (kid) van het gebruikte sleutelpaar bevatten.

JWKS

JWKS is geen eigen standaard, maar komt voor in de OAuth 2.0 Authorization Server Metadata standaard als optionele URL. In de praktijk is het pad <base_url>/.well-known/jwks.json en bevat het document een JSON structuur met in de “keys” waarde een lijst van JSON Web Keys (rfc7517). In koppeltaal wordt deze URL gebruikt door de autorisatie service en optioneel de applicaties, zowel module als portal, om de public keys bekend te maken.

Het access_token en de SMART Scopes syntax.

Het access_token vervult een speciale rol in koppeltaal. Het token bevat de scope dat de rechten aangeeft wat de applicaties permissies zijn. Het access_token wordt ondertekend door de autorisatie service, die op zijn beurt de publieke sleutel bekend maakt via een JWKS url. Verder wordt de waarde van het azp veld gevuld met de client_id van de applicatie. De velden in het access token zijn als volgt gemapped:

iss: de base url van de autorisatie service
azp: de client_id van de applicatie die toegang krijgt
iat: timestamp van uitgifte
exp: geldig tot timestamp, maximaal 5 minuten
scope: de lijst van toegestane permissies, elementen in de lijst worden onderscheiden door een spatie.

De scope bestaat uit een lijst van regels in de SMART Scopes syntax. Deze regels worden opgebouwd vanuit de regels uit permissie matrix van beschreven in het onderdeel TOP-KT-005b - Rollen Matrix. Deze regels worden als volgt toegepast:

De resource wordt gevuld met het resource type, bijvoorbeeld ‘Patient’. Er mag een wildcard ‘*’ gebruikt worden om alle resources aan te duiden. De resource MOET altijd als PascalCase gezet worden.
De actie MOET minimaal één van de onderstaande letters zijn. De letters MOETEN lower-case zijn en hebben de vaste volgorde 'c', 'r', 'u', 'd' en 's'. In het geval alle van toepassing zijn in de matrix (*) wordt cruds gebruikt.
- - 'c' (Create),
  - 'r' (Read), impliceert 's' (Search).
  - 'u' (Update),
  - 'd' (Delete)
  - 's' (Search): binnen koppeltaal is deze gelijk aan 'r' (Read) en moet ook samen met de 'r' (Read) gezet worden.
De scope. Zoals beschreven kan de scope ALL, OWN of GRANTED zijn. In het perrmissiefomaat wordt de volgende mapping gemaakt op de resource-origin parameter die met de device identifiers wordt gevuld op de volgende manier:
- ALL: geen resource-origin parameter
- OWN: de eigen device logical id als resource-origin
- GRANTED: een lijst van device logical ids, gescheiden door een komma als resource-origin parameter.

Deze permissieregels worden in de de SMART Scopes syntax als volgt gemapped:

De SMART Scopes syntax

system/<resource>.<actie(s)>?resource-origin=<device(s)>

In een scope regel kan een type resource worden weergegeven, of een wildcard. Meerdere acties en devices per regel zijn mogelijk.

De scope is case-sensitive. Let op dat de resource altijd middels PascalCase gezet is. De actie dient altijd in lower-case meegegeven te worden.

Scope voorbeelden

Scope	Beschrijving
system/ActivityDefinition.r?resource-origin=13,20	`ActivityDefinitions` met resource-owner `Device/13` en `Device/20` mogen gelezen worden
system/Task.dru	Mag `Tasks` van alle `Devices` deleten, lezen en updaten
system/*.r?resource-origin=13	Alle resources met resource-owner `Device/13` mogen gelezen worden
system/Patient.*?resource-origin=17	Mag alle acties op `Patient` resources uitvoeren met resource-owner `Device/17`
system/*.r	Mag alle resources van alle devices lezen
system/.	Mag alle acties op alle resources van alle devices uitvoeren

Het verkrijgen van toegang in stappen

Voordat het token aangevraagd kan worden gaan we er vanuit dat de volgende situatie van toepassing is:

De applicatie is aangemeld in het domein en heeft zijn public key bekend gemaakt door een JWKS url of door een directe registratie van de public key.
In de FHIR resource service moet een Device zijn aangemaakt waarin de client_id overeenkomt met de applicatie.

De algemene SMART on FHIR backend services flow ziet er als volgt uit:

De applicatie instantie haalt het smart configuratie op bij de FHIR service (.well-known/smart-configuration). De SMART configuratie wordt omschreven in het onderdeel TOP-KT-016 - SMART on FHIR Conformiteit. Dit statement bevat, onder andere, het volgende endpoint:
- token_endpoint
De applicatie maakt zij client assertion door een JWT token met zijn private key te ondertekenen.
- Dit JWT token bevat de volgende headers:
  - typ - De vaste waarde JWT.
  - kid - De Key ID (kid) in het geval gebruik wordt gemaakt van JWKS.
  - alg - zie het onderdeel TOP-KT-008 - Beveiliging aspecten voor welke algoritmen zijn toegestaan in koppeltaal.
- Dit JWT token bevat de volgende velden:
  - iss: de client_id van de applicatie
  - sub: de client_id van de applicatie
  - aud: de URL van het token_endpoint
  - iat: de timestamp now()
  - jti: een unieke waarde voor deze aanvraag, UUIDs zijn hiervoor geschikt.
  - exp: de timestamp now() + 5 minuten
De applicatie benadert het token_endpoint endpoint met de volgende parameters in een application/x-www-form-urlencoded POST request:
- scope: dit veld is verplicht, de inhoud mag leeg blijven. Enige inhoud wordt genegeerd door de autorisatie service.
- grant_type: `client_credentials`
- client_assertion_type: `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`
- client_assertion: het gegenereerde JWT token uit de vorige stap.
De autorisatie service ontvangt het token, daarbij onderneemt hij de volgende stappen:
- Op basis van de domeinconfiguratie wordt de juiste JWKS URL opgehaald om het token te valideren.
- Het token wordt gevalideerd op basis van de Key ID (kid) in de header van het JWT token en de keys beschikbaar in de JWKS URL.
- De client_id wordt gekoppeld aan het juiste Device in de FHIR resource service.
- In de domeinconfiguratie wordt de juiste rol(en) opgehaald, deze wordt vertaald in een lijst van permissies in het formaat zoals beschreven in het onderdeel Het access_token en de SMART Scopes syntax.
De autorisatie service genereert een access_token door het ondertekenen van een JWT.
- De JWT header bevat de volgende waarden:
  - typ - De vaste waarde JWT.
  - kid - De Key ID (kid) van het asymmetrisch sleutelpaar gebruikt voor de ondertekening.
  - alg - zie het onderdeel TOP-KT-008 - Beveiliging aspecten voor welke algoritmen zijn toegestaan in koppeltaal.
- De JWT body bevat de volgende waarden:
  - iss: de base url van de autorisatie service
  - azp: de client_id
  - aud: de vaste waarde welke door de FHIR server vereist is.
  - nbf: timestamp now()
  - jti: een unieke waarde voor dit token, aangeraden wordt om een uuid4 te gebruiken.
  - iat: timestamp now()
  - exp: timestamp now() + 5 min
  - scope: de lijst van permissies, geformatteerd volgens het door koppeltaal vastgelegde formaat zoals omschreven in het onderdeel Het access_token en de SMART Scopes syntax.
  - type: vaste waarde "access"
De autorisatie service geeft het volgende JSON geformateerde antwoord:
- access_token, het JWT token uit de vorige stap.
- token_type: altijd ‘bearer’
- expires_in: overeenkomend met de exp uit het access_token, in dit geval wordt er geen timestamp gegeven, maar het aantal seconden dat het access_token geldig is, standaard 5 min, dus 300s.
- scope: idem als de scope uit het access_token.
De applicatie kan nu de FHIR resource service benaderen door gebruik te maken van het access_token. Het access token wordt in het request in de HTTP Authorization header meegegeven in het volgende formaat:
```
Authorization: Bearer {{access_token}}
```
De FHIR resource service ontvangt het access_token en valideert deze door middel van de public keys beschikbaar in de inhoud van de JWKS URL van de autorisatie service. De Key ID (kid) header in het access_token moet voorkomen als entry in het JWKS bestand. Deze is in de .well-known/smart-configuration van de FHIR resource service beschikbaar.
De FHIR resource service interpreteert de permissies zoals deze in de scope zijn weergegeven en beperkt de toegang van de applicatie op basis van deze permissies.

Voorbeelden

[code]

Links naar gerelateerde onderwerpen

The OAuth 2.0 Authorization Framework

JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants