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:

1. Registreren: Bij het toetreden van een domein wordt voor elke applicatie-instantie een Device resource aangemaakt.
2. Authenticeren: Alle communicatie met de FHIR resource service vereist een access_token . Dit token bevat (indirect) informatie over welke Device dit request uitvoert.
3. 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.
4. 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:

1. Resource: Een permissie is altijd gekoppeld aan een enkele FHIR Domain Resource.

2. Actie: Is van toepassing op een Create (C), Read (R), Update (U) of Delete (D) actie.

3. 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 kunnen op twee manieren doorgegeven worden:

1. Domeinbeheer biedt de mapping aan middels een API call.
2. Domeinbeheer schrijft de records weg in een gedeelde cache/database met de auth server.

Deze laatste oplossing heeft de voorkeur aangezien deze over het algemeen beter te beveiligen is.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 [TODO: LINK TOEVOEGEN] Raadpleeg 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:

Image Removed

De FHIR resource service autoriseert elke binnenkomende CRUD request. Elke request MOET minimaal de volgende logica uitvoeren voor de autorisatie:

Image Removed

Wanneer een request binnenkomt kan de volgende informatie opgehaald worden:

...

Bijvoorbeeld bij een create van een Patient  zijn de volgende scopes valide (in de onderstaande voorbeelden is de logical id van de resource-origin 3a2c98b5-298e-4f95-ab21-077d6b2d2dcc, deze wordt niet gevalideerd aangezien de resource-origin altijd gezet wordt door de FHIR resource service op een create):

...

Mag alle acties uitvoeren op Patient resources met resource-origin Device/3a2c98b5-298e-4f95-ab21-077d6b2d2dcc

...

Zoek een permissie op in de access_token.scope bij de geauthoriseerde applicatie-instantie aan de hand van de logical id van de resource-origin, de <action> en <resource_type>. Bijvoorbeeld: voor een UPDATE op een ActivityDefinition met resource-origin Device/3a2c98b5-298e-4f95-ab21-077d6b2d2dcc kan gezocht worden middels een match op de volgende reguliere expressie:

system\/(?:ActivityDefinition|\*)\.c?r?ud?s?(?:\?[a-z0-9-=&]*resource-origin=3a2c98b5-298e-4f95-ab21-077d6b2d2dcc|(?=\s|$))

Image Removed
Deze regex dwingt af dat er een u voorkomt bij de action. Daarnaast moet OF de resource-origin voorkomen, or GEEN parameter gezet zijn. Dit laatste impliceert een ALL op permissie scope.

...

Image Added

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.

Anchor
search_narrowing search_narrowing

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

...