Beschrijving

...

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.

...

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

...