Se connecter à des applications à l'aide de SMART on FHIR

Aperçu

Cette page décrit les fonctionnalités en version preview qui sont susceptibles d'être modifiées et peuvent avoir 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.

Preview

SMART on 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 SMART (Substitutable Medical Applications, Reusable Technologies) sur FHIR v1.1.0 standard pour accéder aux données des stores FHIR de l'API Cloud Healthcare.

Présentation

SMART on FHIR est une norme de données qui permet aux applications d'accéder aux informations des systèmes de dossiers médicaux électroniques (DME). Les développeurs d'applications peuvent écrire une seule application qui se connecte à tout système de dossiers médicaux électroniques qui a adopté la norme.

Par exemple, si vous disposez de données de patients stockées dans un magasin FHIR dans 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 on FHIR prend en charge les modèles d’autorisation OpenID et OAuth 2.0 pour l'autorisation et l'authentification.

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

L'API Cloud Healthcare est compatible avec le framework de lancement d'applications 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 à partir d'un système DME existant ou d'un portail patient. toutes deux appelées "lancement de DME", ou 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 actuel, la situation rencontrée ou un autre contexte dans laquelle 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 on 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 du magasin 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 un contexte 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 spécifiera pas le workflow de lancement que l'application cliente doit utiliser avec le serveur d'autorisation externe.

Définir et valider les niveaux d'autorisation SMART

Si vous utilisez SMARTProxy, vous pouvez ignorer cette section. SMARTProxy définit et valide automatiquement les habilitations d'autorisation 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 de 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 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, tout type de ressource de la requête pouvant figurer dans un le compartiment patient doit 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 du 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 émet le jeton JWT SMART. 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 JWT SMART, vous pouvez utiliser l'accélérateur d'interopérabilité basé sur Apigee HealthAPIx sur Apigee pour configurer un serveur d'authentification qui signe des 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 offre 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 les éléments suivants : Jetons d'accès SMART dans le cadre de la gestion des API et du modèle d'autorisation.

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 d'un client contenant un jeton SMART.
2. SMARTProxy valide le jeton SMART via votre serveur d'autorisation JWT.
3. SMARTProxy lit les portées 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 via le SMARTProxy au client.

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 service 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 votre compte Google pour l'authentification, Cloud Audit Logs enregistre ensuite votre adresse e-mail comme adresse e-mail principale. Lorsque vous utilisez un proxy pour appeler l'API Cloud Healthcare, le proxy utilise son propre compte de service et 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 magasin FHIR

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

Envoyer des requêtes SMART on 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 de l'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 pour l'application des accès dans l'API Cloud Healthcare. SMART sur FHIR a une liste de Types de ressources FHIR qui peuvent ê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 à 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 ressource patient. Ressource Patient doit déjà exister dans le store FHIR ou exister après l'envoi de la requête, Sinon, l'API Cloud Healthcare rejette la requête.

• Lorsque vous créez, lisez, mettez à jour ou supprimez une ressource, le resourceType et le type d'opération (read ou write) doivent correspondre, sinon l'API Cloud Healthcare rejette 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 de patient est présent avec un champ d'application user, les types de ressources éligibles au compartiment patient sont limités au contexte de 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 comporter le champ subject faisant référence à la ressource Patient donnée pour que la ressource "Observation" soit accessible. Consultez les types d'accès correspondant au compartiment patient dans Resource CompartmentDefinition – Content pour obtenir la liste des champs de chaque type de ressource de compartiment patient doit être référencée au patient donné pour que la ressource soit prise en compte à l'intérieur du 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.