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).

...

SMART on FHIR backend services toegelicht

De SMART on FHIR backend services bestaat uit 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.

Image RemovedImage Added

De aanvraag, het antwoord, en

...

het access token token.

De aanvraag van de applicatie naar de autorisatie service bevat de volgende parametersgebeurt door een POST request met de 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 server kan met de accessResource 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.

Anchor
client_credentials client_credentials

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 authorization service moet 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 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.

Anchor
access_token access_token

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 van de applicatie op basis van de toegewezen rollen. Het 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:

...

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 (TODO: link matrix)het onderdeel TOP-KT-005b - Rollen Matrix. Deze regels worden als volgt toegepast:

...

Het verkrijgen van toegang in stappen

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

...

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

• De module 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 de volgende endpoints, onder andere, het volgende endpoint: 
  • token_endpoint
• De applicatie genereert een JWT token op basis van de private key met 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
de
• • het token te valideren.
De token
• • Het token wordt gevalideerd op basis van de
kid en
• • Key ID (kid) in de header van het JWT token en de keys beschikbaar in de JWKS URL.
  • De client_id wordt gekoppeld aan
de
• • het juiste Device in de FHIR resource service.
  • In de domeinconfiguratie wordt de juiste rol(en) opgehaald, deze
resulteert
• • 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 met 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 
    • 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.
• De autorisatie service geeft het volgende JSON geformateerde antwoord:
  • access_token, het JWT token uit de vorige stap.
  • token_type: altijd ‘bearer’
  • expires_in: idem als de
iat uit de JWT
• • exp uit het access_token.
  • scope:  idem als de scope uit
de JWT
• • het access_token.

• De applicatie kan nu de FHIR resource service benaderen door gebruik te maken van

  de

  het access_token.

  De

  Het access token wordt  in het request in de

  Authorization

  HTTP Authorization header meegegeven in het volgende formaat:
  

  Code Block
  Authorization: Bearer {{access_token}}

  
  

• De FHIR resource service ontvangt de 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.

...

Links naar gerelateerde onderwerpen

The OAuth 2.0 Authorization Framework

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

{}