Beschrijving

...

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

...

De aanvraag van de applicatie naar de autorisatie service gebeurt door gebeurt door een POST request met de de volgende parameters 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.

...

• 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 "fhir-service"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:
  

  Code Block
  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.

...