View a markdown version of this page

SMART auf FHIR OAuth 2.0-Bereichen, unterstützt von HealthLake - AWS HealthLake
Umfang der eigenständigen MarkteinführungDie Ressourcen von SMART auf FHIR umfassen folgende Bereiche HealthLake

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

SMART auf FHIR OAuth 2.0-Bereichen, unterstützt von HealthLake

HealthLake verwendet OAuth 2.0 als Autorisierungsprotokoll. Wenn Sie dieses Protokoll auf Ihrem Autorisierungsserver verwenden, können Sie HealthLake Datenspeicherberechtigungen (Erstellen, Lesen, Aktualisieren, Löschen und Suchen) für FHIR-Ressourcen definieren, auf die eine Client-Anwendung Zugriff hat.

Das SMART on FHIR-Framework definiert eine Reihe von Bereichen, die vom Autorisierungsserver angefordert werden können. Beispielsweise sollte eine Client-Anwendung, die nur darauf ausgelegt ist, dass Patienten ihre Laborergebnisse oder ihre Kontaktdaten einsehen können, nur berechtigt sein, Bereiche anzufordernread.

Anmerkung

HealthLake bietet Unterstützung für SMART auf FHIR V1 und V2, wie unten beschrieben. SMART auf FHIR AuthorizationStrategywird bei der Erstellung Ihres Datenspeichers auf einen der folgenden drei Werte gesetzt:

  • SMART_ON_FHIR_V1— Support nur für SMART auf FHIR V1, einschließlich der Berechtigungen read (read/search) und write (create/update/delete).

  • SMART_ON_FHIR— Support für SMART auf FHIR V1 und V2, einschließlichcreate,read, updatedelete, und search Berechtigungen.

  • AWS_AUTH— Die AWS HealthLake Standard-Autorisierungsstrategie; nicht mit SMART auf FHIR verbunden.

Umfang der eigenständigen Markteinführung

HealthLake unterstützt den Bereich des eigenständigen Startmoduslaunch/patient.

Im eigenständigen Startmodus fordert eine Client-Anwendung Zugriff auf die klinischen Daten des Patienten an, da der Benutzer und der Patient der Client-Anwendung nicht bekannt sind. Daher fordert die Autorisierungsanfrage der Client-Anwendung ausdrücklich die Rückgabe des Patientenbereichs an. Nach erfolgreicher Authentifizierung gibt der Autorisierungsserver ein Zugriffstoken aus, das den angeforderten Patientenstartbereich enthält. Der benötigte Patientenkontext wird zusammen mit dem Zugriffstoken in der Antwort des Autorisierungsservers bereitgestellt.

Unterstützte Bereiche für den Startmodus
Scope Description

launch/patient

Ein Parameter in einer OAuth 2.0-Autorisierungsanfrage, der die Rückgabe von Patientendaten in der Autorisierungsantwort anfordert.

Die Ressourcen von SMART auf FHIR umfassen folgende Bereiche HealthLake

HealthLake definiert drei Ebenen von SMART für FHIR-Ressourcenbereiche.

  • patientBereiche gewähren Zugriff auf spezifische Daten über einen einzelnen Patienten.

  • userBereiche gewähren Zugriff auf bestimmte Daten, auf die ein Benutzer zugreifen kann.

  • systemBereiche gewähren Zugriff auf alle FHIR-Ressourcen, die sich im HealthLake Datenspeicher befinden.

In den folgenden Abschnitten ist die Syntax für die Erstellung von FHIR-Ressourcenbereichen mit SMART auf FHIR V1 oder SMART auf FHIR V2 aufgeführt.

Anmerkung

Die Autorisierungsstrategie von SMART auf FHIR wird bei der Erstellung Ihres Datenspeichers festgelegt. Weitere Informationen finden Sie unter AuthorizationStrategy in der AWS HealthLake -API-Referenz.

SMART auf FHIR V1-Bereichen, unterstützt von HealthLake

Bei der Verwendung von SMART auf FHIR V1 gilt folgende allgemeine Syntax für die Erstellung von FHIR-Ressourcenbereichen. HealthLake Scrollen Sie über die Schaltfläche Kopieren, um den gesamten URL-Pfad im folgenden Beispiel anzuzeigen.

('patient' | 'user' | 'system') '/' (fhir-resource | '*') '.' ('read' | 'write' | '*')
SMART auf FHIR v1 unterstützte Autorisierungsbereiche
Syntax des Geltungsbereichs Beispiel für einen Geltungsbereich Ergebnis

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

 patient/AllergyIntolerance.* Die Client-Anwendung für Patienten hat read/write Zugriff auf Instanzebene auf alle aufgezeichneten Allergien.

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

 user/Observation.read Die Benutzer-Client-Anwendung hat read/write Zugriff auf Instanzebene auf alle aufgezeichneten Beobachtungen.
system/('read' | 'write' | *) system/*.* Die System-Client-Anwendung hat read/write Zugriff auf alle FHIR-Ressourcendaten.

SMART auf FHIR V2-Bereichen, unterstützt von HealthLake

Bei Verwendung von SMART auf FHIR V2 gilt die allgemeine Syntax für die Erstellung von FHIR-Ressourcenbereichen für Folgendes. HealthLake Scrollen Sie über die Schaltfläche Kopieren, um den gesamten URL-Pfad im folgenden Beispiel anzuzeigen.

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

Um SMART auf FHIR V2 zu verwenden, müssen Sie den Wert permission-v2in die capabilities Metadatenzeichenfolge übergeben, die ein Mitglied des IdentityProviderConfigurationDatentyps ist.

HealthLake unterstützt detaillierte Bereiche. Weitere Informationen finden Sie unter Unterstützte detaillierte Bereiche im FHIR US Core Implementation Guide.

SMART auf FHIR V2 unterstützte Autorisierungsbereiche
Syntax des Geltungsbereichs Beispiel für einen V1-Bereich Ergebnis

patient/Observation.rs

 user/Observation.read Erlaubnis zum Lesen und Durchsuchen der Observation Ressource für den aktuellen Patienten.

system/*.cruds

 system/*.* Die System-Client-Anwendung hat vollen create/read/update/delete/search-Zugriff auf alle FHIR-Ressourcendaten.

SMART auf FHIR-Bereichen V2.2 , unterstützt von HealthLake

V2.2 erweitert die V2-Bereiche um eine Filterung, die auf Suchparametern basiert. Autorisierungsserver können jetzt Bereiche vergeben, die den Zugriff anhand bestimmter Datenmerkmale einschränken und nicht nur nach Ressourcentyp und CRUDS-Vorgang.

Alles von V2 bleibt unverändert. V2.2 ist rein additiv:

  • Bestehende V2-Bereiche (ohne Filter) funktionieren weiterhin wie zuvor.

  • Die V2-Grammatik wird um eine optionale ?param=value Abfragezeichenfolge erweitert.

  • Keine Änderungen an den Bereichsebenen (patient/user/system), Ressourcentypen oder CRUDS-Buchstaben.

Voraussetzungen

Bevor Sie SMART auf FHIR aktivieren V2.2, stellen Sie Folgendes sicher:

  • Ihr Datenspeicher wurde mit der AuthorizationStrategy Einstellung auf erstellt SMART_ON_FHIR (unterstützt sowohl V1 als auch V2). Datenspeicher, die SMART_ON_FHIR_V1 oder nicht verwenden, AWS_AUTH sind berechtigt.

  • Ihr Datenspeicher ist bereits permission-v2 im capabilities Array enthalten. V2.2 ist additiv, da es V2 erweitert und nicht eigenständig verwendet werden kann.

  • Ihr IDP-Lambda ist so konfiguriert, dass es das V2.2 Bereichsformat (Bereiche, die ? Abfragesyntax enthalten) validiert und durchläuft.

Aktiviert V2.2

Der Aktivierungspfad hängt davon ab, ob Sie einen neuen Datenspeicher erstellen oder einen vorhandenen aktualisieren.

Neue Datenspeicher

Wenn Sie einen neuen Datenspeicher erstellen, permission-v2.2 fügen Sie dem capabilities Array im Metadata Feld Folgendes hinzu IdentityProviderConfiguration:

"capabilities": [
  "launch-ehr",
  "sso-openid-connect",
  "client-public",
  "permission-v2",
  "permission-v2.2"
]
Bestehende Datenspeicher

Um SMART auf FHIR V2.2 in einem vorhandenen Datenspeicher permission-v2.2 zu aktivieren, fügen Sie es dem capabilities Array in Ihrem Metadata Feld hinzu IdentityProviderConfigurationund senden Sie die Änderung mitUpdateFHIRDatastore. Weitere Informationen finden Sie unter Aktualisieren eines HealthLake Datenspeichers.

Voraussetzungen:

  • permission-v2muss im Array verbleiben. V2.2 erweitert V2 und kann nicht alleine verwendet werden.

  • AuthorizationStrategymuss SMART_ON_FHIR (nicht SMART_ON_FHIR_V1 oderAWS_AUTH) sein.

  • Durch die Aktualisierung der Identity Provider-Konfiguration wird sie vollständig ersetzt. Schließen Sie also alle vorhandenen Felder und Funktionen mit einpermission-v2.2.

Die Änderung wird sofort und ohne Ausfallzeiten wirksam. Rufen Sie zur Überprüfung Folgendes ab Discovery-Dokument (erfordert SigV4):

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

Wenn das capabilities Array in der Antwort Folgendes enthältpermission-v2.2, ist SMART auf FHIR aktiv V2.2 .

Syntax für erweiterten Geltungsbereich

Die V2-Grammatik wird um eine optionale Abfragezeichenfolge erweitert:

V2:   (patient|user|system) / resource . cruds
V2.2: (patient|user|system) / resource . cruds [? param=value [& param=value ...]]
V2.2 Komponenten der Gültigkeitsbereichsabfragezeichenfolge
Komponente Description

?param=value

Search-parameter filtern. Nur Ressourcen, die diesem Kriterium entsprechen, sind zugänglich.

&param=value

Zusätzlicher Filter. Mehrere Filter sind UND-verknüpft — alle müssen übereinstimmen.

Regeln:

  • Filter gelten nur für den im Bereich angegebenen Ressourcentyp. Wildcard (*) mit Filtern wird nicht unterstützt.

  • Die Parameter müssen für den Ressourcentyp gemäß der Suchkonfiguration Ihres Datenspeichers gültig sein (überprüfen Sie dies überGET /r4/metadata).

  • Die Zeichenfolge mit dem vollständigen Gültigkeitsbereich (z. B.patient/Observation.rs?category=laboratory) ist der Literalwert, der im OAuth 2.0-Bereichsparameter und im Zugriffstoken-Anspruch erscheint. scp

  • URL-encode Sonderzeichen gemäß RFC 6749 in Autorisierungsanfragen (z. B. →). | %7C

  • V2.2 Unterstützt Präfixvergleicher für Datums-, Zahlen- und Mengenparameter (z. B.). ?date=eq2023-01-01 V2.2 unterstützt auch Suchparameter-Modifikatoren.

Beispiele für den Geltungsbereich

V2.2 Beispiele für den Anwendungsbereich
Scope Zugriff gewährt

patient/DiagnosticReport.rs?category=LAB

Nur DiagnosticReport Ressourcen wo category sindLAB.

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

Nur Observation Ressourcen mit SicherheitslabelRestricted.

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

Nur Observation Ressourcen, die am oder nach dem 1. Januar 2023 datiert wurden.

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

Nur Observation Ressourcen, die Labor- UND Endversionen sind.

user/Condition.rs?clinical-status=active

Nur aktive Condition Ressourcen.

Verhalten bei der Durchsetzung

Wenn ein Token V2.2 Bereiche enthält, werden Filter pro Vorgang HealthLake angewendet:

V2.2 Durchsetzung pro Vorgang
Operation Behavior

Lesen (r)

Nur erfolgreich, wenn die Ressource allen Bereichsfiltern entspricht. Andernfalls wird 403 zurückgegeben.

Suche (s)

Bereichsfilter überschneiden sich mit der Abfrage. Es werden nur passende Ressourcen zurückgegeben.

Create/Update (c/u)

Die Ressource muss die Bereichsfilter erfüllen, um geschrieben zu werden. Andernfalls wird 403 zurückgegeben.

Löschen (d)

Die Zielressource muss den Bereichsfiltern entsprechen. Andernfalls wird 403 zurückgegeben.
Vorrang des Geltungsbereichs

  • Mehrere V2.2 Bereiche für denselben Ressourcentyp sind vereinigt (ODER bereichsübergreifend).

  • Ein breiterer V2-Bereich ohne Filter (z. B.patient/Observation.rs) gewährt vollen Zugriff, unabhängig von etwaigen V2.2 engeren Bereichen im selben Token.

  • V2.2 Bereiche in einem Datenspeicher ohne permission-v2.2 Aktivierung werden stillschweigend ignoriert.

Einschränkungen

Folgendes wird in V2.2 Bereichsfiltern nicht unterstützt:

  • Zusammengesetzte Suchparameter (z. B.code-value-quantity).

  • Verkettete Suchparameter (z. B.subject:Patient.name=Smith).

  • _include/_revincludeSuchparameter.

  • $export/$davinci-data-export(Massendaten) — V2.2 Filter gelten nicht; beim Massenexport werden V2-Bereiche verwendet.

  • Ressourcentyp mit Platzhaltern kombiniert mit Filtern (z. B. patient/*.rs?category=LAB ist ungültig). Sie müssen einen expliziten Ressourcentyp angeben, wenn Sie Suchparameterfilter verwenden (z. B.). patient/Observation.rs?category=LAB

Fehlerbehebung
Symptom Ursache Korrigieren

Der Token-Bereich wurde nicht erkannt

V2.2 im Datenspeicher nicht aktiviert

Überprüfen Sie die Aktivierung /.well-known/smart-configuration und fordern Sie sie über ein Support-Ticket an.

403 auf einer vorhandenen Ressource

Die Ressource entspricht nicht dem Bereichsfilter

Überprüfen Sie die Ressourcenwerte anhand der Bereichsparameter.

Leere Suchergebnisse

Der Bereichsfilter ist enger als die Abfrage

Die Ergebnisse sind der Schnittpunkt von Abfrage- und Bereichsfiltern.

InvalidScope-Fehler

Ungültiger Suchparameter im Gültigkeitsbereich

Bestätigen Sie den Parameter über /metadata CapabilityStatement.

End-to-end Beispiel

Szenario: Eine Patienten-App sollte ab 2023 nur endgültige Laborergebnisse anzeigen.

  1. Der Autorisierungsserver gibt ein Token mit folgendem Gültigkeitsbereich aus:

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

  2. Der Client ruft an HealthLake:

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

  3. HealthLake erzwingt Bereichsfilter. Die Antwort enthält nur Observation Ressourcen mit category=laboratory UND status=final UND, date ≥ 2023-01-01 obwohl der Client alle Beobachtungen angefordert hat.