View a markdown version of this page

SMART sur les oscilloscopes FHIR OAuth 2.0 pris en charge par HealthLake - AWS HealthLake
Périmètre de lancement autonomeSMART sur les champs de ressources FHIR pour HealthLake

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

SMART sur les oscilloscopes FHIR OAuth 2.0 pris en charge par HealthLake

HealthLake utilise OAuth 2.0 comme protocole d'autorisation. L'utilisation de ce protocole sur votre serveur d'autorisation vous permet de définir HealthLake des autorisations de stockage de données (création, lecture, mise à jour, suppression et recherche) pour les ressources FHIR auxquelles une application cliente a accès.

Le framework SMART on FHIR définit un ensemble de portées qui peuvent être demandées au serveur d'autorisation. Par exemple, une application client conçue uniquement pour permettre aux patients de consulter leurs résultats de laboratoire ou de consulter leurs coordonnées ne doit être autorisée qu'à demander read des scopes.

Note

HealthLake fournit un support pour SMART sur FHIR V1 et V2, comme décrit ci-dessous. Le SMART on FHIR AuthorizationStrategyest défini sur l'une des trois valeurs suivantes lors de la création de votre magasin de données :

  • SMART_ON_FHIR_V1— Support uniquement pour SMART sur FHIR V1, qui inclut les read autorisations (read/search) et write (create/update/delete).

  • SMART_ON_FHIR— Support de SMART sur FHIR V1 et V2, qui inclutcreate,read, updatedelete, et search les autorisations.

  • AWS_AUTH— La stratégie AWS HealthLake d'autorisation par défaut ; non affiliée à SMART on FHIR.

Périmètre de lancement autonome

HealthLake prend en charge le champ launch/patient d'application du mode de lancement autonome.

En mode de lancement autonome, une application client demande l'accès aux données cliniques du patient car l'utilisateur et le patient ne sont pas connus de l'application cliente. Ainsi, la demande d'autorisation de l'application cliente demande explicitement que le dossier du patient soit renvoyé. Une fois l'authentification réussie, le serveur d'autorisation émet un jeton d'accès contenant le champ d'application du patient de lancement demandé. Le contexte patient nécessaire est fourni avec le jeton d'accès dans la réponse du serveur d'autorisation.

Champs d'application du mode de lancement pris en charge
Scope Description

launch/patient

Paramètre d'une demande d'autorisation OAuth 2.0 demandant que les données du patient soient renvoyées dans la réponse d'autorisation.

SMART sur les champs de ressources FHIR pour HealthLake

HealthLake définit trois niveaux de SMART sur les étendues de ressources FHIR.

  • patientles scopes donnent accès à des données spécifiques concernant un seul patient.

  • userles étendues donnent accès à des données spécifiques auxquelles un utilisateur peut accéder.

  • systemles étendues donnent accès à toutes les ressources FHIR présentes dans le magasin de HealthLake données.

Les sections suivantes répertorient la syntaxe permettant de créer des étendues de ressources FHIR à l'aide de SMART sur FHIR V1 ou SMART sur FHIR V2.

Note

La stratégie d'autorisation SMART on FHIR est définie lors de la création de votre magasin de données. Pour plus d’informations, consultez AuthorizationStrategy dans la Référence d’API AWS HealthLake .

SMART sur les oscilloscopes FHIR V1 pris en charge par HealthLake

Lorsque vous utilisez SMART sur FHIR V1, la syntaxe générale pour la construction des étendues de ressources FHIR est la suivante. HealthLake Pour afficher le chemin complet de l'URL dans l'exemple suivant, faites défiler le curseur sur le bouton Copier.

('patient' | 'user' | 'system') '/' (fhir-resource | '*') '.' ('read' | 'write' | '*')
Champs d'autorisation pris en charge par SMART on FHIR v1
Syntaxe Scope Exemple de champ d'application Résultat

patient/(fhir-resource | '*').('read' | 'write' | '*')

 patient/AllergyIntolerance.* L'application client du patient dispose d'un read/write accès au niveau de l'instance à toutes les allergies enregistrées.

user/(fhir-resource | '*').('read' | 'write' | '*')

 user/Observation.read L'application cliente utilisateur dispose d'un read/write accès au niveau de l'instance à toutes les observations enregistrées.
system/('read' | 'write' | *) system/*.* L'application cliente du système a read/write accès à toutes les données des ressources FHIR.

SMART sur les oscilloscopes FHIR V2 pris en charge par HealthLake

Lorsque vous utilisez SMART sur FHIR V2, la syntaxe générale pour la construction des étendues de ressources FHIR est la suivante. HealthLake Pour afficher le chemin complet de l'URL dans l'exemple suivant, faites défiler le curseur sur le bouton Copier.

('patient' | 'user' | 'system') '/' (fhir-resource | '*') '.' ('c' | 'r' | 'u' | 'd' | 's')
Note

Pour utiliser SMART sur FHIR V2, vous devez transmettre la valeur permission-v2dans la capabilities chaîne de métadonnées, qui est membre du type de IdentityProviderConfigurationdonnées.

HealthLake prend en charge les oscilloscopes granulaires. Pour plus d'informations, voir les étendues granulaires prises en charge dans le guide de mise en œuvre de FHIR US Core.

Étendue d'autorisation compatible avec SMART on FHIR V2
Syntaxe Scope Exemple de scope V1 Résultat

patient/Observation.rs

 user/Observation.read Autorisation de lire et de rechercher Observation une ressource pour le patient actuel.

system/*.cruds

 system/*.* L'application cliente du système dispose d'un accès complet create/read/update/delete/search à toutes les données de ressources FHIR.

SMART sur les V2.2 oscilloscopes FHIR compatibles avec HealthLake

V2.2 étend le champ d'application de la V2 avec un filtrage basé sur les paramètres de recherche. Les serveurs d'autorisation peuvent désormais émettre des étendues qui limitent l'accès en fonction de caractéristiques de données spécifiques et pas uniquement en fonction du type de ressource et du fonctionnement du CRUDS.

Tout reste inchangé depuis la V2. V2.2 est purement additif :

  • Les oscilloscopes V2 existants (sans filtres) continuent de fonctionner comme avant.

  • La grammaire V2 est étendue avec une chaîne de ?param=value requête facultative.

  • Aucune modification des niveaux de portée (patient/user/system), des types de ressources ou des lettres CRUDS.

Conditions préalables

Avant d'activer SMART sur FHIR V2.2, assurez-vous de ce qui suit :

  • Votre magasin de données a été créé avec AuthorizationStrategy set to SMART_ON_FHIR (supporte à la fois les versions V1 et V2). Les magasins de données utilisent SMART_ON_FHIR_V1 ou ne AWS_AUTH sont pas éligibles.

  • Votre magasin de données est déjà inclus permission-v2 dans le capabilities tableau. V2.2 est additif car il étend la V2 et ne peut pas être utilisé seul.

  • Votre IDP Lambda est configuré pour valider et transmettre le format de portée (étendues ? contenant V2.2 la syntaxe de requête).

Activant V2.2

Le chemin d'activation varie selon que vous créez un nouveau magasin de données ou que vous mettez à jour un magasin existant.

Nouveaux magasins de données

Lorsque vous créez un nouveau magasin de données, ajoutez-le permission-v2.2 au capabilities tableau dans le Metadata champ de votre IdentityProviderConfiguration:

"capabilities": [
  "launch-ehr",
  "sso-openid-connect",
  "client-public",
  "permission-v2",
  "permission-v2.2"
]
Magasins de données existants

Pour activer SMART sur FHIR V2.2 sur un magasin de données existant, ajoutez-le permission-v2.2 à la capabilities matrice dans le Metadata champ de votre IdentityProviderConfigurationet soumettez la modification avecUpdateFHIRDatastore. Pour de plus amples informations, veuillez consulter Mettre à jour un magasin HealthLake de données.

Prérequis:

  • permission-v2doit rester dans le tableau. V2.2 étend la V2 et ne peut pas être utilisée seule.

  • AuthorizationStrategydoit être SMART_ON_FHIR (pas SMART_ON_FHIR_V1 ouAWS_AUTH).

  • La mise à jour de la configuration du fournisseur d'identité la remplace dans son intégralité. Incluez donc tous les champs et fonctionnalités existantspermission-v2.2.

La modification prend effet immédiatement, sans interruption de service. Pour vérifier, récupérez le Document de découverte (nécessite SigV4) :

GET {healthlake-endpoint}/r4/.well-known/smart-configuration

Si le capabilities tableau indiqué dans la réponse inclutpermission-v2.2, SMART sur FHIR V2.2 est actif.

Syntaxe à portée étendue

La grammaire V2 est étendue avec une chaîne de requête facultative :

V2:   (patient|user|system) / resource . cruds
V2.2: (patient|user|system) / resource . cruds [? param=value [& param=value ...]]
V2.2 composants de chaîne de requête scope
Composant Description

?param=value

Search-parameter filtre. Seules les ressources répondant à ce critère sont accessibles.

&param=value

Filtre supplémentaire. Les filtres multiples sont des filtres ANDED ; ils doivent tous correspondre.

Règles :

  • Les filtres s'appliquent uniquement au type de ressource spécifié dans le champ d'application. Wildcard (*) avec filtres n'est pas pris en charge.

  • Les paramètres doivent être valides pour le type de ressource conformément à la configuration de recherche de votre magasin de données (vérifiez viaGET /r4/metadata).

  • La chaîne de portée complète (par exemple,patient/Observation.rs?category=laboratory) est la valeur littérale qui apparaît dans le paramètre de portée OAuth 2.0 et dans la demande de jeton d'accès. scp

  • URL-encode caractères spéciaux conformément à la RFC 6749 dans les demandes d'autorisation (par exemple, | →%7C).

  • Pour les paramètres de date, de nombre et de quantité, V2.2 prend en charge les comparateurs de préfixes (par exemple,?date=eq2023-01-01). V2.2 prend également en charge les modificateurs de paramètres de recherche.

Exemples de scopes

V2.2 exemples de scopes
Scope Accès accordé

patient/DiagnosticReport.rs?category=LAB

Seules les DiagnosticReport ressources là où elles category se trouventLAB.

patient/Observation.rs?_security=http://terminology.hl7.org/CodeSystem/v3-Confidentiality|R

Uniquement Observation les ressources dotées d'une étiquette de sécuritéRestricted.

patient/Observation.rs?date=ge2023-01-01

Uniquement Observation les ressources datées du 1er janvier 2023 ou après cette date.

patient/Observation.rs?category=laboratory&status=final

Uniquement Observation les ressources qui sont de laboratoire ET finales.

user/Condition.rs?clinical-status=active

ConditionRessources actives uniquement.

Comportement d'application

Lorsqu'un jeton inclut V2.2 des étendues, HealthLake applique des filtres par opération :

V2.2 mise en œuvre par opération
Opération Comportement

Lisez (r)

Réussit uniquement si la ressource correspond à tous les filtres de portée. Sinon, renvoie 403.

Rechercher (s)

Les filtres de portée sont intersectés avec la requête. Seules les ressources correspondantes sont renvoyées.

Create/Update (c/u)

La ressource doit satisfaire aux filtres de portée pour être écrite. Sinon, renvoie 403.

Supprimer (d)

La ressource cible doit correspondre aux filtres de portée. Sinon, renvoie 403.
Priorité du champ

  • Plusieurs V2.2 étendues pour le même type de ressource sont unifiées (OU entre plusieurs étendues).

  • Une portée V2 plus large sans filtres (par exemple,patient/Observation.rs) accorde un accès complet indépendamment des V2.2 étendues plus étroites dans le même jeton.

  • V2.2 les étendues d'un magasin de données non permission-v2.2 activées sont ignorées silencieusement.

Limitations

Les éléments suivants ne sont pas pris en charge dans les filtres V2.2 d'étendue :

  • Paramètres de recherche composites (par exemple,code-value-quantity).

  • Paramètres de recherche enchaînés (par exemple,subject:Patient.name=Smith).

  • _include/paramètres _revinclude de recherche.

  • $export/$davinci-data-export(Bulk Data) : V2.2 les filtres ne s'appliquent pas ; l'exportation en bloc utilise des étendues V2.

  • Type de ressource générique combiné à des filtres (par exemple, non patient/*.rs?category=LAB valide). Vous devez spécifier un type de ressource explicite lorsque vous utilisez des filtres de paramètres de recherche (par exemple,patient/Observation.rs?category=LAB).

Résolution des problèmes
Symptôme Cause Corriger

La portée du jeton n'est pas reconnue

V2.2 non activé sur le magasin de données

Vérifiez /.well-known/smart-configuration et demandez l'activation via un ticket d'assistance.

403 sur une ressource qui existe

La ressource ne correspond pas au filtre de portée

Vérifiez les valeurs des ressources par rapport aux paramètres de portée.

Résultats de recherche vides

Le filtre de portée est plus étroit que celui de la requête

Les résultats sont l'intersection des filtres de requête et de portée.

InvalidScopeErreur

Paramètre de recherche non valide dans le champ d'application

Confirmez le paramètre via /metadata CapabilityStatement.

End-to-end exemple

Scénario : une application destinée aux patients ne devrait afficher les résultats de laboratoire finalisés qu'à partir de 2023.

  1. Le serveur d'autorisation émet un jeton dont la portée est la suivante :

    patient/Observation.rs?category=laboratory&status=final&date=ge2023-01-01

  2. Appels du client HealthLake :

    GET {endpoint}/r4/Observation?patient=Patient/123

  3. HealthLake applique les filtres de scope. La réponse contient uniquement Observation des ressources où category=laboratory ET status=final ETdate ≥ 2023-01-01, même si le client a demandé toutes les observations.