Nouveaux Scopes SMART on FHIR v2
Dans la version v2026.1, nous avons introduit la prise en charge d'un système d'autorisation plus robuste et plus sécurisé pour vos points de terminaison FHIR.
Ceci est rendu possible grâce à l'utilisation des SMART on FHIR v2 à granularité fine.
Objectif - Pas SMART en général, mais plutôt les scopes à granularité fine ; Un exemple pratique et simple
Je vous ai déjà parlé du sujet SMART on FHIR auparavant, notamment danscet article que j'ai rédigé (accompagné d'une application Open Exchange, et d'une série de vidéos connexes).
D'autres auteurs ont également abordé ce sujet, notamment @Luis Angel Pérez Ramos dans sa série d'articles intitulée Développement d'applications SMART On FHIR avec Auth0 et le serveur FHIR d'InterSystems IRIS, @Nicole Sun dans son article Lancement d'un DME SMART on FHIR avec IRIS for Health, et @Kate Lau dans son article en deux parties intitulé UPostman pour le test de l'OAuth 2.0 du référentiel FHIR d'InterSystems.
De plus, la vidéo Learning Services intitulée Configuration d'OAuth pour le serveur FHIR d'InterSystems - explique clairement ce sujet et présente même une partie du tout dernier filtrage des résultats basé sur les scopes SMART dont nous allons parler ici.
Cependant, dans les articles et exemple susmentionnés, nous avons soit utilisé InterSystems IRIS lui-même comme serveur OAuth, soit un serveur OAuth cloud tiers (tel que auth0 d'Okta), mais dans cet article et cet exemple, je souhaite procéder de manière légèrement différente -
1. Je souhaite utiliser un serveur OAuth tiers, mais pas un serveur qui nécessite une inscription (et éventuellement des frais). Nous allons utiliser Keycloak.
2. Je vais m'occuper de toute la configuration pour vous dans un exemple Dockerisé -
- InterSystems IRIS for Health opérationnel avec un point de terminaison FHIR défini, y compris un client OAuth, et quelques ressources dans le référentiel.
- Keycloak opérationnel avec un client correspondant au client OAuth d'IRIS.
- Une collection Postman permettant de procéder rapidement à des tests et à des démonstrations.
3. Je tiens à me concentrer sur les Scopes SMART v2 à granularité fine qui sont relativement récents, et non sur les Scopes SMART de base. C'est vraiment l'essentiel ici. Les deux autres éléments mentionnés ci-dessus nous permettent justement de nous concentrer uniquement sur ce point.
Scopes SMART - Version à granularité fine
J'ai généré ci-dessus (merci à NotebookLM) une infographie claire qui résume la syntaxe générale et l'utilisation des scopes SMART.
Je souhaite notamment mettre l'accent sur la partie filtre, c'est-à-dire la partie des scopes qui commence par le point d'interrogation (?).
Ici, il est possible d'utiliser la syntaxe FHIR Search standard, avec les paramètres de recherche FHIR standard.
Voici un exemple:
Au lieu d'autoriser tout simplement l'accès (lecture & recherche dans ce cas) à toutes les catégories d'observations, nous n'autorisons ici que l'accès aux résultats de laboratoire (catégorie = laboratoire).
À titre d'exemple, au lieu d'avoir accès à un ensemble tel que celui-ci:
On peut limiter l'accès à un ensemble par exemple comme ça:
Cela permet d'adopter une approche ABAC (contrôle d'accès basé sur les attributs) pour accéder aux données FHIR (pour en savoir plus sur ce sujet, consultez la documentation FHIR).
Certaines réglementations nationales exigent la mise en œuvre de ce type de contrôle d'accès, notamment par l'utilisation de balises de sécurité pour limiter l'accès aux données.
On peut citer comme exemple la certification ONC aux États-Unis, mais d'autres pays ont des exigences similaires.
La prise en charge de cette fonctionnalité est donc non seulement importante pour sécuriser vos données, mais elle constitue également une exigence impérative de la législation locale dans un nombre croissant de pays.
Possibilité de filtrer (ou non)
Vous pouvez choisir, si la requête FHIR ne respecte pas strictement les scopes, soit de filtrer les données non autorisées et de ne renvoyer que celles qui sont autorisées, soit de rejeter la requête et de renvoyer une erreur 403 (code d'état HTTP).
Ce paramètre se trouve dans les paramètres d'autorisation du point de terminaison FHIR:
Il convient de noter que cela s'applique non seulement aux scopes à granularité fine, mais aussi lorsque le filtre ? n'est pas utilisé. Par exemple, si vous employez l'opération _include ou $everything, cela pourrait entraîner le filtrage de « tous » les types de ressources du jeu de résultats.
Voici un exemple -
Exemple de recherche d'observations
Supposons que nous lancions une recherche d'observations en utilisant l'authentification de base, de sorte qu'aucun SCOPE SMART ne soit appliqué.
Comme vous pouvez le constater ici, nous obtenons 793 ressources.
En y regardant de plus près, on constate par exemple que la première appartient à la catégorie des signes vitaux:
En comparaison, si j'utilise l'authentification OAuth 2 avec un scope utilisateur/Observation.rs?category=laboratory, on n'obtient que 385 ressources (contre 793 ci-dessus):
Et la première (au lieu de « signes vitaux ») relève en réalité de la catégorie des analyses de laboratoire:
On peut observer une comparaison similaire avec $everything -
Exemple d' $everyting
Avec l'authentification de base (sans scope):
Nous obtenons bien sûr la ressource « Patient » elle-même, mais aussi les ressources associées (comme dans l'exemple ci-dessus) : Consultation (Encounter), Professionnel de santé (Practitioner), Organisation (Organization), Pathologie (Condition), Demande de remboursement (Claim), Relevé de prestations (ExplanationOfBenefit), Observation (de différents types), Demande de médicaments (MedicationRequest), Vaccination (Immunization), Rapport diagnostique (DiagnosticReport)
Avec OAuth (et des scopes qui incluent uniquement: user/Patient.rs and user/Observation.rs?category=laboratory):
Ici, hormis le patient lui-même, nous n'avons que des observations (laboratoires) et aucune autre ressource associée.
Ainsi, 171 ressources contre 35 après le filtrage.
Quelques remarques techniques
- Comme indiqué, la version 2026.1 ou supérieure est requise pour prendre en charge cette fonctionnalité.
- La plupart des interactions FHIR sont prises en charge pour ce type de scopes ( Création, Lecture, Mise à jour, Suppression, Recherche), mais certaines ne le sont pas encore (Historique, VRead)
- Comme indiqué dans la chaîne de recherche du filtre, vous pouvez utiliser la syntaxe de recherche FHIR standard, mais certains paramètres n'ont tout simplement pas de sens dans ce contexte (comme _include) ; par conséquent, certains peuvent entraîner l'échec de la requête et d'autres peuvent simplement être ignorés. Consultez la documentation référencée pour plus de détails.
- Il existe quelques remarques concernant $everything et $lastn ; là encore, consultez la documentation pour plus de détails.
Débogage
Lors de l'utilisation d'OAuth en général, et des scopes SMART en particulier, tout ne fonctionnera pas toujours comme prévue au début.
Le journal du serveur FHIR (ou FSLOG) et le journal des requêtes HTTP (ou ISCLOG) constituent de bonnes ressources pour déboguer votre situation ; pour plus de détails, consultez la documentation ici.
Voici un exemple -
Imaginons que nous ayons désactivé les paramètres de filtrage des résultats et que nous essayions de rechercher toutes les observations alors que notre scope n'autorise que les résultats de laboratoire.
Nous obtiendrons une erreur avec le code de statut HTTP 403 (Forbidden):
Et si nous activons le journal du serveur FHIR, nous pouvons voir quelque chose comme ceci:
Exemple de démonstration
Aborder un sujet de manière pratique permet toujours de mieux le comprendre et d'approfondir les connaissances. Je vous invite donc à essayer l'application Open Exchange correspondante. Il s'agit d'un exemple très simple, prêt à l'emploi : un fichier docker compose se charge de configurer et de lancer tout ce dont vous avez besoin, et comprend une collection Postman type que vous pouvez tester.