Document toolboxDocument toolbox

ATH - Eisen (en aanbevelingen) voor toegangsbeheersing

Owned by Bernard Stibbe
Last updated: Jun 21, 2023 by Marcel Schrauwen
5 min read

Toegangsbeheersing is gebaseerd op het kunnen identificeren van applicaties. Authenticatie is het proces om de identiteit te kunnen achterhalen.

001. Voordat een applicatie instantie een verbinding kan opzetten met de "FHIR Resource Provider", MOET de applicatie Instantie een asymmetrische sleutelpaar genereren of verkrijgen en MOET hij zijn openbare sleutel registreren bij de Autorisatie Server van de "FHIR Resource Provider". SMART zelf vereist geen op standaarden gebaseerd registratie proces, maar we moedigen ontwikkelaars aan om het "OAuth 2.0 Dynamic Client Registration Protocol" te gebruiken [RFC-7591].   

002. Authenticatie en autorisatie bij Koppeltaal 2.0 vereist het gebruik van OAuth 2.0-bearer tokens, verkregen met behulp van het mechanisme dat wordt beschreven in Paragraaf 4.4 van [RFC-6749].

003. Om misbruik met (toegang) tokens te voorkomen, MOET men de toegangstokens beschermen bij opslag en transport [zie RFC-6750]. 

004. Elke applicatie instantie gebruikt het toegangstoken om zich te authentiseren met de bron met behulp van het HTTP-autorisatieverzoek headerveld [RFC-2617] met een authenticatieschema gedefinieerd door de specificatie van het gebruikte toegangstokentype, zoals [RFC-6750].

005. Een applicatie instantie genereert een JWT [RFC7519]- bearer token als middel voor authenticatie bij het aanvragen van een (OAuth 2.0) - toegangstoken, dat hij vervolgens kan gebruiken om verzoeken aan services te autoriseren volgens [RFC-7523].

006. Een applicatie instantie MOET een handtekening element kunnen genereren door het algoritme toe te passen op de inhoud van zowel de header- als de payload-elementen [zie RFC-7515] voor het kunnen maken van een JSON Web Signature, (JWS). 

007. Voor het bevragen en/of aanleveren van data bij de "FHIR Resource Provider" MOET men gebruik maken van een toegangstoken (access_token). Indien men geen toegangstoken heeft krijgt men geen toegang tot de “FHIR Resource Provider”.

008. Het OAuth2 Access Token Service Endpoint is de locatie waar de applicatie instantie het toegangstoken kan verkrijgen. Het OAuth2 Access Token Service Endpoint MOET bij de applicatie instantie bekend zijn en MOET opvraagbaar zijn bij de “FHIR Resource Provider”. 

009. Alle applicatie instanties (Portalen, eHealth Modules, etc) MOETEN zich bij de Autorisatie Server registreren.

010. Elke applicatie instantie KAN bij de registratie een unieke client_id ontvangen van de Autorisatie Server, die de applicatie Instantie MOET gebruiken bij het aanvragen van een toegangstoken. De Autorisatie Server verleent, via het toegangstoken de applicatie instantie toegang tot de "FHIR Resource Provider".

011. Voor elk afgegeven client_id door de Autorisatie Server wordt er een Device automatisch toegevoegd bij de "FHIR Resource Provider" met als Device.identifier de client_id.

012. De  "FHIR Resource Provider" voegt automatisch een resource-origin extensie toe en een searchParameter voor de resource-origin, als deze nog niet bestaan. 

013. De resource-origin extensie wordt alleen door de "FHIR Resource Provider" gezet. De extensie meegeven in een POST resulteert in een foutmelding. 

014. Toegangstokens (en sleutels) mogen NIET gebruikt worden in query parameters.

015. De applicatie instantie ZAL altijd gebruik maken van TLS (Transport Layer Security), [zie RFC-5246] of meer recente versie van TLS v1.3 [zie RFC-8446] , voor de communicatie met de Autorisatie Server van de FHIR Resource Provider om uitgewisselde informatie af te schermen en te versleutelen. Indien men RFC-8446 gebruikt, is RFC-5246 verouderd. Met TLS kunnen client-/server toepassingen via internet communiceren op een manier die is ontworpen om afluisteren, knoeien en vervalsing van berichten te voorkomen.

016. Bij de aanvraag van een toegangstoken door de applicatie instantie (Portaal of eHealth Module) om hiermee de eigen administratie (interne data) gelijk te houden aan de data (resources) van de “FHIR Resource Provider” (Zie bv: http://hl7.org/fhir/uv/bulkdata/2021May/authorization.html#smart-backend-services-authorization), is de aanvraag gebaseerd op de Client Credentials Flow. Zie hoofdstuk 4.4. Client Credentials Grant van RFC-6749 en [RFC-7523] (hoofdstuk 2 Client Authentication)

017. De applicatie instantie beschermt zijn eigen geheime sleutel en is daarvoor verantwoordelijk. 

018. Elke applicatie instantie MOET in staat zijn om een JSON handtekening te genereren (JWS) in overeenstemming met [RFC-7515].

019. De JWT MOET met een asymmetrische publieke/geheime sleutel ondertekend worden.

020. De publieke sleutel MOET van elke applicatie instantie beschikbaar zijn voor validatie van de JSON handtekening en MAG via het JWKS protocol [RFC-7517] verspreid worden. De Autorisatie Server geeft voor elke tenant (of domein) een jwks_uri eindpunt weer, dat men kan vinden op https://YOUR_DOMAIN/.well-known/jwks.json. Dit eindpunt bevat de JWK die wordt gebruikt om alle door de Autorisatie Server uitgegeven JWT's voor deze tenant (of domein) te ondertekenen. 

021. De publieke sleutel of de jwks_uri van de applicatie instantie MAG (direct) geregistreerd worden bij de Autorisatie Server. De sleutels worden als PKCS8 formaat opgevoerd. De applicatie instantie is zelf verantwoordelijk voor het rouleren van de publieke sleutel behorende bij applicatie instantie.

022. De ondertekening MOET gebruik maken van een asymmetrisch algoritme, dus alle op HMAC gebaseerde ALGORITMEN (algoritmen die beginnen met HS) zijn NIET toegestaan.

023. De validerende partij MOET de volgende asymmetrische algoritmen kunnen ondersteunen (zie [RFC-7518 - 3.1]):

a. RS256 (Aanbevolen), RS384 (Optioneel) en RS512 (Optioneel)

b. ES256 (Aanbevolen), ES384 (Optioneel)en ES512 (Optioneel)

024. Bij de aanbevolen asymmetrische algoritme MOET een sleutel van 2048 bits of groter worden gebruikt.

025. Elke applicatie instantie is zelf verantwoordelijk voor zijn eigen (interne) data, qua beveiliging en logging en moeten voldoen aan de NEN-7510 en NEN-7513.

026. Bij het ontbreken van de juiste (unieke) toegangstoken dient de statuscode 401 Access Denied terug te worden gegeven.

027. Bij Koppeltaal worden er ondertekende tokens tussen applicaties uitgewisseld dat verifieerbare informatie bevat. De ontvanger van deze tokens heeft een manier nodig om deze token te kunnen verifiëren. Voor het kunnen authentiseren en valideren van deze tokens zal een aparte Introspectie Endpoint bij de Autorisatie Server moeten worden ingericht. Zie voor specificaties RFC7662.

028. Het token Introspectie Endpoint moet informatie over een token kunnen retourneren, dus dit Endpoint zit meestal op dezelfde locatie waar de (toegang) tokens worden uitgegeven.

029. Het token Introspectie URL Endpoint kan via de FHIR server (store) “/metadata”  URL worden opgevraagd.

030. Het verzoek om een token te laten valideren gebeurt met een POST-verzoek dat alleen een parameter met de naam "token" bevat.

031. Het  token Introspectie Endpoint wordt niet publiekelijk beschikbaar gesteld en wordt met een toegangstoken afgeschermd.

032. Volgende validatie wordt uitgevoerd op specifiek HTI (Health Tools Interoperability) tokens bij ontvangst door een gelanceerde applicatie of Autorisatie Server via het Introspectie Endpoint :

a. De digitale handtekening op het (HTI) token MOET gevalideerd worden. m.b.v. de publieke sleutel van de issuer (c)

b. Eis 023 is ook van toepassing op het HTI-token.

c. De issuer identifier waarde MOET een verwijzing zijn naar de lancerende applicatie die het (HTI) token maakt en digitaal ondertekend heeft. 

d. De Audience waarde MOET een verwijzing zijn voor wie het (HTI) token bedoeld is. De gelanceerde partij.

e. De jti waarde is een unieke identifier voor deze (HTI) token instantie. Mag maar één keer in een token gebruikt worden. 

f. De iat waarde is een timestamp wanneer het (HTI) token is aangemaakt

g. De exp waarde geeft het verlooptijdstip aan tot wanneer het (HTI) token geldig is.

h. De Subject waarde geeft aan, aan welke gebruiker dit (HTI) token is afgegeven. 

i. De Task waarde is een FHIR Task resource in JSON formaat

j. De FHIR Version waarde is optioneel, afhankelijk van de ondersteunende Task release.

Aanbevelingen

a001. Leveranciers en uitvoerders moeten ervoor zorgen dat ze bekend zijn met OAuth2 threat model en alle beveiligingsoverwegingen, die in [RFC-6819]  worden behandeld.

a002. Leveranciers en uitvoerders worden aanbevolen op de hoogte te zijn van de laatste OAuth 2.0 best practices die in [OAuth2-SBP] worden behandeld.

a003. Leveranciers en uitvoerders worden aanbevolen op de hoogte te zijn van de laatste JWT best practices die in [RFC-8725] worden behandeld.

a004. OpenID Connect 1.0 is een eenvoudige identiteit laag bovenop het OAuth 2.0-protocol. Het stelt klanten in staat om de identiteit van de eindgebruiker te verifiëren op basis van de authenticatie uitgevoerd door een Identity Provider , en om basisprofielinformatie over de eindgebruiker te verkrijgen op een interoperabele en REST-achtige manier. Deze specificatie definieert de kernfunctionaliteit van OpenID Connect: authenticatie bovenop OAuth 2.0 en het gebruik van claims om informatie over de eindgebruiker te communiceren. Het beschrijft ook de veiligheids- en privacyoverwegingen voor het gebruik van [OpenID Connect].