Versiegeschiedenis

Versie	Datum	Status	Wijzigingen
0.1.0	13 Dec 2022	concept	Scopes herschreven n.a.v. SMART v2
0.1.1	19 Dec 2022	concept	Device parameter waarde aangepast conform SMART v2 (referentie i.p.v. logical id)

Beschrijving

Binnen Koppeltaal krijgt elke applicatie-instantie (een applicatie binnen een domein) een rol toegekend. Deze rol bepaalt welke acties uitgevoerd mogen worden op de FHIR resource service.

Overwegingen

Een domein bevat meerdere applicatie-instanties. Lang niet altijd zullen alle applicaties in een domein data van elkaar gebruiken. Vanwege het privacy-by-design principe mogen applicaties geen onnodige resources opvragen. Dit moet zo min mogelijk impact hebben op de eindgebruikers. Zo is de FHIR resource service bijvoorbeeld verantwoordelijk voor het filteren van informatie op een “GET all”-request.

Helaas is er binnen FHIR geen gestandaardiseerde manier om dit op te lossen. Het staat dienstverleners vrij om een gepast autorisatiemodel toe te passen. Als oplossing hiervoor is een Role Based Access Control (verder: RBAC) autorisatiemodel ontwikkeld. Deze oplossing moet goed passen op de brede set aan functionaliteiten die de FHIR http en search specificaties bieden.

Toepassing en restricties

Autorisatiemodel

Kernpunten

Als oplossing is een RBAC autorisatiemodel tot stand gekomen middels deze vier uitgangspunten:

Registreren: Bij het toetreden van een domein wordt voor elke applicatie-instantie een Device resource aangemaakt.
Authenticeren: Alle communicatie met de FHIR resource service vereist een access_token . Dit token bevat (indirect) informatie over welke Device dit request uitvoert.
Eigenaarschap: Alle resources die aangemaakt worden op de FHIR resource service, krijgen automatisch een resource-origin extensie. Deze extensie refereert naar de gekoppelde Device resource van de geauthenticeerde applicatie-instantie.
Autoriseren: Alle CRUD-acties die plaatsvinden op een resource, worden - aan de hand van de resource-origin extensie en de rol van de geauthenticeerde applicatie-instantie - geautoriseerd.

Rollen en permissies

Het autorisatiemodel is een op RBAC-gebaseerd model. Een applicatie-instantie krijgt maximaal één rol toegekend vanuit het domeinbeheer stelselcomponent. Deze rol is gekoppeld aan een set van permissies. Elke permissie bevat de volgende informatie:

Resource: Een permissie is altijd gekoppeld aan een enkele FHIR Domain Resource.
Actie: Is van toepassing op een Create (C), Read (R), Update (U) of Delete (D) actie.

Scope: Heeft één van de volgende scopes:

Scope	Beschrijving
OWN	De permissie is enkel van toepassing op resources waarvan de `resource-origin` overeenkomt met de geauthenticeerde applicatie-instantie.
GRANTED	De permissie is van toepassing op resources waarvan de `resource-origin` overeenkomt met één van de geselecteerde applicatie-instantie(s).
ALL	De permissie is van toepassing op alle resources in het domein.

Registreren van Devices

Wanneer een applicatie een domein toetreedt, krijgt deze applicatie-instantie een client_id toegekend. Het domeinbeheer stelselcomponent heeft de verantwoordelijkheid om een Device resource aan te maken op de FHIR resource service. Deze Device MOET de volgende identifier bevatten:

{
  "system": "<https://koppeltaal.nl/client_id>",
  "value": "<CLIENT_ID>"
}

Mappen van `access_token` naar Device

Wanneer een access_token opgehaald wordt door een applicatie-instantie, MOET deze altijd het azp veld bevatten. Dit veld wordt door de autorisatieserver gevuld met de client_id van de applicatie die de access_token opvraagt. Aangezien elke Device resource een https://koppeltaal.nl/client_id identifier moet hebben, kan de mapping plaatsvinden.

Rollen en permissies van Domeinbeheer naar authorizatie server

Het domeinbeheer stelselcomponent beheert de rollen en bijbehorende permissies. Deze permissies worden door middel van de scope in het access_token meegegeven.

Permissies zetten op `access_token.scope`

Bij het uitgeven van een access_token MOET de autorisatieserver de gekoppelde permissies omzetten naar het scope veld. Raadpleeg TOP-KT-005c - Applicatie toegang: SMART on FHIR backend services voor de exacte uitwerking hiervan.

Toekennen `resource-origin` aan resources

De FHIR resource service MOET voor elke Resource die aangemaakt worden de resource-origin extensie toevoegen. Op deze manier is per Resource altijd te achterhalen wat het bronsysteem is van deze Resource. Koppeltaal maakt expliciet gebruik van deze extensie aangezien er een Reference naar een Device dient te zijn. FHIR zelf heeft het Resource.meta.source veld. Echter is deze van het type URI, en daarom te ambigu voor dit doeleinde.

De applicatie-instantie mag de resource-origin extensie NIET zelf zetten op een POST. De resource-origin MAG wel meegegeven worden aan een PUT. In dit geval MOET de FHIR resource server valideren dat deze ongewijzigd is. Indien de resource-origin extensie NIET gezet is in een PUT, MOET de FHIR resource service deze zetten.

Autoriseren

Voor het autoriseren wordt gebruik gemaakt van de V2 scopes uit de SMART app launch. De uitgegeven scopes zijn een subset van de V2 scopes, en hebben altijd de resource-origin parameters. Daarnaast heeft ons RBAC-model geen s permissie. Deze wordt altijd gezet door de auth server wanneer de client een r permissie heeft. De volgende syntax wordt gehanteerd:

De value van de resource-origin parameter is altijd een comma-separated lijst van Device referenties. In het geval van een GRANTED permissie kunnen hier dus meerdere waarden staan.

Het autoriseren MOET a.d.h.v. de scope op het access_token plaatsvinden. Binnen Koppeltaal MOET de resource-origin parameter op alle scopes gezet worden die geen ALL permissie hebben. De waarde van deze parameter MOET comma-separated zijn indien er meer dan één resource-origin toegestaan is.

Autoriseren van een "Read all" request

Wanneer een applicatie-instantie geen specifieke instantie van een resource opvraagt, maar zoekt naar bijv. alle Patient resources, dient de resource-origin value gebruikt te worden voor Search Narrowing. Deze wordt later in het document toegelicht.

Autoriseren van een resource instantie request

Alle niet-"read all"-requests betreffen (binnen Koppeltaal) altijd een CRUD-operatie op een enkele instantie van een resource. Indien het geen create betreft, betreft het ook altijd een bestaande resource. Er is dan altijd een resource-origin extensie aanwezig. De FHIR resource service MOET nagaan of de applicatie-instantie toegang heeft tot deze resource n.a.v. de resource type, actie en de resource-origin van de bestaande resource. Indien de gebruiker geen toegang heeft MOET er geantwoord worden met een HTTP code 403.

Search Narrowing

Wanneer alle resources opgehaald worden voor een specifiek type, bijv. GET /Patient, mogen enkel de resources teruggegeven worden waar de applicatie-instantie leesrechten op heeft. Dit wordt door de FHIR resource service opgelost middels een interceptor pattern. De oplossing dient de huidige query-parameters te filteren en uit te breiden in het geval dat de permissie scope niet ALL is.

De volgende flow wordt gehanteerd:

Subscription Narrowing

Het toevoegen van search narrowing kan als gevolg hebben dat de FHIR resource service een Subscription afvuurt terwijl een applicatie-instantie daar geen toegang toe heeft. Bij het aanmaken van Subscriptions dient dezelfde logica toegepast te worden als bij search narrowing, alleen dan op de Subscription.criteria.

Links naar gerelateerde onderwerpen

Onderwerp	Link
FHIR HTTP spec	https://www.hl7.org/fhir/r4/http.html
FHIR Search	https://www.hl7.org/fhir/r4/search.html
SMART App Launch scopes	http://hl7.org/fhir/smart-app-launch/scopes-and-launch-context.html
Search narrowing code voorbeeld	https://github.com/Koppeltaal/Koppeltaal-2.0-FHIR-HAPI-Server/blob/master/src/main/java/ca/uhn/fhir/jpa/starter/koppeltaal/interceptor/ResourceOriginSearchNarrowingInterceptor.java
Subscription narrowing code voorbeeld	https://github.com/Koppeltaal/Koppeltaal-2.0-FHIR-HAPI-Server/blob/master/src/main/java/ca/uhn/fhir/jpa/starter/koppeltaal/interceptor/SubscriptionInterceptor.java
Zetten van resource-origin code voorbeeld	https://github.com/Koppeltaal/Koppeltaal-2.0-FHIR-HAPI-Server/blob/master/src/main/java/ca/uhn/fhir/jpa/starter/koppeltaal/interceptor/InjectResourceOriginInterceptor.java
Autorisatie code voorbeeld	https://github.com/Koppeltaal/Koppeltaal-2.0-FHIR-HAPI-Server/blob/master/src/main/java/ca/uhn/fhir/jpa/starter/koppeltaal/interceptor/ResourceOriginAuthorizationInterceptor.java
Domeinbeheer topic	Domeinbeheer Topic
FHIR resource service toegang topic	Applicatie toegang: SMART on FHIR backend services
Interceptor Pattern	https://en.wikipedia.org/wiki/Interceptor_pattern

Browser not supported