Se connecter à des applications en utilisant SMART sur FHIR

Preview

Cette page décrit des fonctionnalités en preview qui sont susceptibles d'être modifiées et d'une assistance limitée. Les modifications apportées aux produits et fonctionnalités pré-DG peuvent ne pas être compatibles avec d'autres versions pré-DG. Pour en savoir plus, consultez les conditions de l'offre pré-DG pour l'API Cloud Healthcare et les descriptions des étapes de lancement.

Aperçu

SMART sur FHIR n'est disponible qu'avec l'API v1beta1. L'API v1 renvoie une erreur si une requête inclut des en-têtes SMART.

Cette page explique comment utiliser la norme SMART (Substitutable Medical Applications, Reusable Technologies) sur FHIR v1.1.0 pour accéder aux données des stores FHIR de l'API Cloud Healthcare.

Présentation

SMART sur FHIR est une norme de données qui permet aux applications d'accéder aux informations de systèmes de dossiers médicaux électroniques (DME). Un développeur d'applications peut écrire une seule application qui se connecte à n'importe quel système DME ayant adopté cette norme.

Par exemple, si vous avez stocké des données de patients dans un store FHIR de l'API Cloud Healthcare, vous pouvez développer une application qui effectue les opérations suivantes:

1. S'authentifie auprès du magasin FHIR.
2. Récupère les données du patient.
3. Affiche les données du patient dans une interface utilisateur.

SMART sur FHIR prend en charge les modèles d’autorisation OpenID et OAuth 2.0 pour l’autorisation et l’authentification.

Framework de lancement d’application SMART, portées et contexte de lancement

L'API Cloud Healthcare prend en charge le framework de lancement d'application SMART, les champs d'application et le contexte de lancement comme suit:

Framework de lancement d'application SMART

L'API Cloud Healthcare est compatible avec la séquence de lancement autonome du framework de lancement d'application SMART.

Une application peut être lancée depuis un système DME existant ou une session de portail patient. Ces deux opérations sont appelées "lancement de DME", ou bien en tant qu'application autonome.

Niveaux d'accès

Les champs d'application des données cliniques définissent des autorisations de lecture et d'écriture pour l'accès spécifique au patient et au niveau de l'utilisateur. L'API Cloud Healthcare accepte les champs d'application de données suivants définis sur la page Champs d'application pour demander des données cliniques :

• patient
• user
• system

Contexte de lancement

Décrit le patient, la rencontre ou tout autre contexte dans lequel la demande est effectuée. L'API Cloud Healthcare prend en charge le contexte de lancement du patient à partir des champs d'application pour demander des données de contexte.

Configurer votre serveur d'autorisation pour SMART sur FHIR

L'API Cloud Healthcare fournit une prise en charge intégrée de l'application d'accès SMART on FHIR en fonction des champs d'application des autorisations SMART d'entrée et du contexte des patients. Les administrateurs de magasins FHIR créent et configurent un serveur d'autorisation en dehors de l'API Cloud Healthcare qui accorde des champs d'application d'autorisation SMART et le contexte du patient.

Si une application cliente obtient un jeton d'accès représentant les champs d'application d'autorisation SMART accordés et le contexte du patient, l'API Cloud Healthcare ne précise pas le workflow de lancement que l'application cliente doit utiliser avec le serveur d'autorisation externe.

Définir et valider les champs d'application des autorisations SMART

Si vous utilisez SMARTProxy, vous pouvez ignorer cette section. SMARTProxy définit et valide automatiquement les champs d'application des autorisations SMART.

Les champs d'application des autorisations SMART utilisent le format suivant :

( 'patient' | 'user' | 'system') '/' ( resourceType | '*' ) '.' ( 'read' | 'write' | '*' )

Les champs d'application des autorisations SMART et les contextes de patient sont transmis à l'API Cloud Healthcare à l'aide des en-têtes HTTP X-Authorization-. L'API Cloud Healthcare utilise ces en-têtes pour appliquer le contrôle des accès aux données des magasins FHIR.

Votre serveur d'autorisation attribue les champs d'application d'autorisations SMART et le contexte du patient et les encode dans un jeton d'accès. Le proxy lit ensuite les informations dans le jeton d'accès et les transmet dans les en-têtes de requête FHIR.

Si vous ne disposez pas d'un serveur d'autorisation, vous pouvez utiliser l'accélérateur d'interopérabilité basé sur Apigee, HealthAPIx, sur Apigee.

Utilisez les en-têtes HTTP SMART on FHIR suivants lors de l'envoi de requêtes à partir du proxy. L'application cliente n'a pas besoin de définir ces en-têtes, car ils ne sont transmis que du proxy à l'API Cloud Healthcare.

• X-Authorization-Scope : un ou plusieurs champs d'application d'autorisation qui utilisent les formats standards de champ d'application SMART. Par exemple, définir le champ d'application d'autorisation sur user/Observation.read signifie qu'une requête ne peut lire qu'une ressource "Observation". L'API Cloud Healthcare applique ce contrôle d'accès.
• X-Authorization-Patient : contexte du patient de la requête. Lorsque vous définissez cet en-tête, tous les types de ressources de la requête qui peuvent se trouver dans un compartiment patient doivent appartenir au compartiment patient de l'ID patient fourni. L'API Cloud Healthcare applique ce contrôle d'accès.
• X-Authorization-Subject : identifiant de l'utilisateur final accédant à l'application cliente SMART on FHIR. L'API Cloud Healthcare consigne le sujet dans les journaux d'audit.
• X-Authorization-Issuer : émetteur de jetons d'accès SMART. L'API Cloud Healthcare consigne l'émetteur dans les journaux d'audit.

Configurer les jetons d'accès au serveur d'autorisation

Pour émettre un jeton JWT, vous devez configurer un serveur d'autorisation. Le jeton JWT contient les champs d'application des autorisations SMART et, éventuellement, le contexte du patient. L'API Cloud Healthcare n'a pas d'exigences spécifiques concernant la manière dont le serveur d'autorisation génère le jeton SMART JWT. Par exemple, votre application peut être enregistrée pour un sous-ensemble de champs d'application ou elle peut présenter un widget de sélection de patient pour définir le contexte du patient.

Si vous ne disposez pas d'un serveur d'autorisation qui configure les jetons SMART JWT, vous pouvez utiliser l'accélérateur d'interopérabilité basé sur Apigee, HealthAPIx, sur Apigee pour configurer un serveur d'authentification qui signe les jetons JWT.

Exemple de jeton d'accès

L'exemple suivant montre un jeton d'accès encodé en base64 :

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzM4NCJ9.eyJpc3MiOiJzbWFydC50b2tlbi5vcmciLCJpYXQiOjE2MTI4ODQwODUsImV4cCI6MTY0NDQyMDA4NSwiYXVkIjoid3d3LmV4YW1wbGUuY29tIiwic3ViIjoiZG9jdG9yLmpvZUBleGFtcGxlLmNvbSIsInNjb3BlIjoidXNlci9QcmFjdGl0aW9uZXIucmVhZCBwYXRpZW50LyouKiIsInBhdGllbnQiOiJwYXRpZW50MTIzIn0.lC0ouNuXNcj7FxQ83NU_MInULWo0wvyiNuaMt2RbFzBOnnMP_IXJdCeNnw3SQzUV

Après avoir décodé le jeton d'accès, il contient la charge utile suivante:

{
  "iss": "smart.token.org",
  "iat": 1612884085,
  "exp": 1644420085,
  "aud": "www.example.com",
  "sub": "[e-mail]",
  "scope": "user/Practitioner.read patient/*.*",
  "patient": "patient123"
}

Configurer SMART sur FHIR dans l'API Cloud Healthcare

Cette section décrit la procédure à suivre pour commencer à utiliser SMART on FHIR avec des données dans l'API Cloud Healthcare.

Configurer SMARTProxy

Si vous utilisez votre propre serveur d'autorisation au lieu de SMARTProxy, ignorez cette section et passez à la section Configurer un compte de service Google Cloud.

SMARTProxy est un proxy Open Source de Google qui fournit les fonctionnalités suivantes :

• Permet à l'API Cloud Healthcare d'accepter et de valider les jetons d'accès SMART.
• Permet à l'implémentation FHIR dans l'API Cloud Healthcare d'inclure des jetons d'accès SMART dans le modèle de gestion et d'autorisation des API.

Lorsque vous effectuez une requête pour récupérer des données à partir de l'API Cloud Healthcare via SMARTProxy, la requête suit les étapes ci-dessous :

1. SMARTProxy accepte une requête contenant un jeton SMART d’un client.
2. SMARTProxy valide le jeton SMART via votre serveur d’autorisation JWT.
3. SMARTProxy lit les champs d'application et le contexte du patient à partir du jeton SMART et les transmet à l'API Cloud Healthcare à l'aide de quatre en-têtes HTTP.
4. L'API Cloud Healthcare reçoit les en-têtes et les valide pour appliquer le contrôle des accès à la requête. L'API Cloud Healthcare renvoie ensuite une réponse au client via SMARTProxy.

Configurer un compte de service Google Cloud

Un proxy ne peut avoir qu'un seul compte de service Google Cloud. Si plusieurs clients utilisent le même proxy, ils doivent utiliser le même compte de service. Soyez prudent lorsque vous partagez un compte de service avec plusieurs clients pour les raisons suivantes :

• Pour lire les données FHIR dans l'API Cloud Healthcare, le compte de service dispose d'autorisations étendues en lecture et en écriture.

• L'adresse e-mail principale des journaux d'audit Cloud est liée au compte de service.

  Par exemple, si vous appelez l'API Cloud Healthcare à l'aide de votre compte Google pour l'authentification, Cloud Audit Logs enregistre votre adresse e-mail en tant qu'adresse e-mail principale. Lorsque vous appelez l'API Cloud Healthcare à l'aide d'un proxy, celui-ci utilise son propre compte de service. L'adresse e-mail du compte de service est l'adresse e-mail principale. L'appelant d'origine est donc masqué. Pour enregistrer l'utilisateur final dans les métadonnées du journal d'audit, transmettez l'adresse e-mail de l'utilisateur final dans le champ sub du jeton JWT.

Configurer un store FHIR

Vous n'avez pas besoin de configurer le store FHIR contenant les données FHIR auxquelles vous accédez.

Effectuer des tâches SMART sur les requêtes FHIR

Cette section présente les méthodes SMART on FHIR prises en charge par l'API Cloud Healthcare, ainsi que la façon dont l'accès aux ressources est appliqué lorsque vous effectuez une requête SMART on FHIR.

Lors d'une requête, votre serveur d'autorisation est chargé de générer des jetons d'accès avec le champ d'application d'autorisation SMART approprié et le contexte de lancement.

Méthodes acceptées

L'API Cloud Healthcare prend en charge SMART on FHIR pour toutes les méthodes projects.locations.datasets.fhirStores.fhir, à l'exception des éléments suivants :

• fhir.ConceptMap-search-translate
• fhir.ConceptMap-translate
• fhir.Resource-validate

Application des accès aux ressources

Lorsque vous effectuez une requête SMART on FHIR vers un magasin FHIR, le contrôle de l'accès se produit dans l'ordre suivant :

1. L'API Cloud Healthcare vérifie les autorisations sur le compte de service Google Cloud configuré dans le proxy. Si le compte de service dispose des autorisations IAM appropriées sur le magasin FHIR, la requête aboutit.
2. L'API Cloud Healthcare vérifie si le jeton SMART dispose des autorisations appropriées pour accéder à chaque ressource FHIR demandée par la requête.

Le compartiment patient est essentiel à la logique d'application des accès dans l'API Cloud Healthcare. SMART on FHIR dispose d'une liste de types de ressources FHIR pouvant être inclus dans un compartiment patient. Les types de ressources possèdent également leurs propres critères d'inclusion. Dans le reste de cette section, les types de ressources éligibles sont appelés "types de ressources patient éligibles au compartiment". Les types de ressources non éligibles sont appelés "types de ressources patient non éligibles au compartiment".

Les requêtes SMART sur FHIR adressées à un store FHIR doivent répondre aux exigences suivantes:

• Indiquez le rôle patient, user ou system dans les champs d'application des autorisations SMART. Si vous indiquez le rôle patient, vous devez fournir un contexte du patient. Le contexte du patient est un ID logique de la ressource patient. La ressource Patient doit déjà exister dans le store FHIR ou existe après l'envoi de la requête. Sinon, l'API Cloud Healthcare la rejette.

• Lors de la création, de la lecture, de la mise à jour ou de la suppression d'une ressource, la valeur resourceType et le type d'opération (read ou write) doivent correspondre. Sinon, l'API Cloud Healthcare refuse la requête.

• Si vous fournissez un champ d'application patient contenant des types de ressources non éligibles au compartiment patient, tels que patient/Practitioner.*, la vérification du champ d'application échoue et l'API Cloud Healthcare rejette le champ d'application.

• Vous pouvez définir tous les types de ressources avec le champ d'application user. Si un contexte patient est présent avec un champ d'application user, les types de ressources éligibles aux compartiments patients sont limités au contexte du patient. Les types de ressources restants ignorent le contexte du patient.

• La présence d'un contexte de patient limite les types de ressources éligibles au compartiment patient au patient donné. Par exemple, une ressource Observation doit faire référence au champ subject à la ressource Patient donnée pour que l'Observation soit accessible. Consultez les types d'accès aux compartiments patient dans Resource CompartmentDefinition - Content pour obtenir la liste des champs de chaque type de ressource de compartiment patient qui doivent être référencés au patient donné pour que la ressource soit prise en compte dans le compartiment patient.

• Les requêtes peuvent contenir à la fois des champs d'application patient et user.

• N'utilisez pas le champ d'application system avec le contexte du patient, sinon la requête échouera.

• N'utilisez pas le champ d'application system avec le champ d'application patient ou user.

• Si vous appelez une méthode qui accède à plusieurs ressources (par exemple, fhir.Patient-everything, fhir.executeBundle ou fhir.search), le contrôle d'accès s'applique à chaque ressource.