Kurze Antwort: SMART App Launch (SMART on FHIR) ist die Spezifikation von HL7, wie eine App autorisierten Zugriff auf einen FHIR-Server im Namen eines Benutzers erhält. Es ist OAuth 2.0 und OpenID Connect mit FHIR-spezifischen Konventionen: ein Discovery-Dokument unter .well-known/smart-configuration; zwei Launch-Modi (EHR Launch, bei dem die EHR die App im Kontext des aktuellen Patienten öffnet, und Standalone Launch, bei dem der Benutzer die App öffnet und einen Patienten auswählt); Scopes in einer FHIR-fähigen Syntax (patient/Observation.rs bedeutet Lesen und Suchen von Observationen des Patienten im Kontext); Launch-Kontext, der mit dem Token zurückgegeben wird (welcher Patient, welche Begegnung); und Backend-Dienste für System-zu-System-Zugriff mit signierter JWT-Client-Authentifizierung. SMART v2 (ab 2021) hat PKCE obligatorisch gemacht, granulare Scopes und asymmetrische Client-Authentifizierung hinzugefügt und ist die Version, die nationale Programme verlangen.
Schritt 1: Discovery
Die SMART App Launch Discovery beginnt damit, dass die App das Dokument .well-known/smart-configuration des FHIR-Servers abruft. Dieses Dokument listet die Autorisierungs- und Token-Endpunkte, die unterstützten Funktionen (EHR-Launch, Standalone-Launch, öffentliche und vertrauliche Clients, OpenID Connect, Patienten- und Benutzerberechtigungen), die unterstützten Scopes, die PKCE-Code-Challenge-Methoden und die Grant-Typen auf. So weiß die App, wohin sie den Benutzer senden soll.
GET https://fhir.example-hospital.org/.well-known/smart-configuration
{
"issuer": "https://auth.example-hospital.org",
"authorization_endpoint": "https://auth.example-hospital.org/authorize",
"token_endpoint": "https://auth.example-hospital.org/token",
"introspection_endpoint": "https://auth.example-hospital.org/introspect",
"capabilities": ["launch-ehr", "launch-standalone", "client-public", "client-confidential-asymmetric", "sso-openid-connect", "context-ehr-patient", "context-standalone-patient", "permission-patient", "permission-user", "permission-v2", "permission-offline"],
"scopes_supported": ["openid", "fhirUser", "launch", "launch/patient", "patient/*.rs", "user/*.rs", "offline_access"],
"code_challenge_methods_supported": ["S256"],
"grant_types_supported": ["authorization_code", "client_credentials"]
}
Die App erfährt, wohin sie den Benutzer senden soll und was der Server unterstützt.
Schritt 2: Launch
SMART App Launch hat zwei Launch-Modi. Bei einem EHR-Launch öffnet der Kliniker die App innerhalb des EHR, das einen iss-Parameter (den FHIR-Server) und ein undurchsichtiges Launch-Token übergibt, das den aktuellen Patienten und die Begegnung kodiert. Bei einem Standalone-Launch öffnet der Benutzer die App direkt und der Autorisierungsserver bittet ihn, einen Patienten auszuwählen oder zu bestätigen.
EHR Launch. Der Kliniker klickt auf die App innerhalb der EHR; die EHR öffnet die Launch-URL der App mit zwei Parametern: iss (der FHIR-Server) und launch (ein undurchsichtiges Token, das den aktuellen Patienten und die Begegnung kodiert). Die App muss launch in ihrer Autorisierungsanfrage mit dem launch-Scope wiederholen.
Standalone Launch. Der Benutzer öffnet die App direkt; die App kennt den FHIR-Server (ausgewählt oder konfiguriert) und fragt nach dem Kontext mit launch/patient; der Autorisierungsserver bittet den Benutzer, einen Patienten auszuwählen oder zu bestätigen.
Schritt 3: Autorisierungscode mit PKCE
Der SMART-Autorisierungsschritt ist der OAuth 2.0 Autorisierungscode-Flow mit PKCE: Die App sendet den Benutzer mit ihren Scopes, dem aud des FHIR-Servers und einer Code-Challenge an den Autorisierungs-Endpunkt. Der Benutzer authentifiziert sich und genehmigt die Anfrage. Die App tauscht den zurückgegebenen Code und den Code-Verifier gegen ein Zugriffstoken aus, das zusammen mit dem Launch-Kontext ankommt.
GET https://auth.example-hospital.org/authorize?
response_type=code&client_id=my-app&redirect_uri=https://app.example.org/cb
&scope=openid%20fhirUser%20launch%20patient/Observation.rs%20patient/Condition.rs%20offline_access
&state=af0ifjsldkj&aud=https://fhir.example-hospital.org
&launch=xyz123&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256
Der Benutzer authentifiziert sich (mit dem Identitätsanbieter des Krankenhauses) und genehmigt die Scopes; der Server leitet mit einem code zurück; die App tauscht ihn aus:
POST https://auth.example-hospital.org/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code=...&redirect_uri=https://app.example.org/cb&client_id=my-app&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
{
"access_token": "eyJhbGciOi...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "openid fhirUser launch patient/Observation.rs patient/Condition.rs offline_access",
"refresh_token": "a8c3...",
"id_token": "eyJhbGciOi...",
"patient": "Patient/123",
"encounter": "Encounter/456",
"fhirUser": "Practitioner/42",
"need_patient_banner": true,
"smart_style_url": "https://ehr.example.org/styles/smart.json"
}
Der Launch-Kontext (patient, encounter, fhirUser) kommt zusammen mit dem Token an. Öffentliche Clients (mobile und Browser-Apps) verwenden PKCE und kein Client-Geheimnis; vertrauliche Clients authentifizieren sich mit einem Geheimnis oder, vorzugsweise, mit einem signierten JWT (private_key_jwt) unter der asymmetrischen Methode.
Scopes
SMART on FHIR v2 Scopes verwenden die Syntax context/resource.permissions, wobei context patient, user oder system ist und permissions c, r, u, d und s für create, read, update, delete und search kombiniert, wie in patient/Observation.rs. Granulare Scopes fügen einen Filter hinzu, openid und fhirUser geben die Identität des Benutzers an, Launch-Scopes fordern Kontext an und offline_access fordert ein Refresh-Token an.
SMART v2-Syntax: <context>/<resource>.<permissions> wobei Kontext patient (der Patient im Kontext), user (was auch immer der Benutzer sehen darf) oder system (Backend) ist, und Berechtigungen sind c create, r read, u update, d delete, s search, in dieser Reihenfolge: patient/Observation.rs, user/Patient.rs, system/*.cruds. Granulare Scopes fügen einen Filter hinzu: patient/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|vital-signs. openid fhirUser geben ein ID-Token und die FHIR-Identität des Benutzers; launch, launch/patient, launch/encounter fordern Kontext an; offline_access ein Refresh-Token für die Nutzung, wenn der Benutzer abwesend ist, online_access eines, das nur während der Sitzung gültig ist. Die v1-Syntax (patient/Observation.read) wird von vielen Servern immer noch akzeptiert.
Backend-Dienste
Für ein System, das ohne Benutzer agiert (ein nächtlicher Export, eine Integrations-Engine), verwendet SMART Backend Services client_credentials mit einer signierten JWT-Assertion (die öffentlichen Schlüssel des Clients, veröffentlicht unter einer JWKS-URL) und system/-Scopes. Kein Benutzer, kein Launch-Kontext, strenge Registrierung.
Sicher ausführen
Die sichere Ausführung von SMART App Launch bedeutet, exakte Redirect-URIs zu registrieren, niemals den impliziten Flow zu verwenden, Refresh-Tokens sicher zu speichern und zu rotieren, state und den aud von ID-Tokens zu validieren, Tokens bei jedem API-Aufruf zu verifizieren, sowohl Scopes als auch den Patientenkontext auf der Datenebene durchzusetzen, sodass ein Token für einen Patienten niemals einen anderen liest, und jeden Zugriff zu protokollieren.
Registrieren Sie exakte Redirect-URIs; verwenden Sie niemals den impliziten Flow; speichern Sie Refresh-Tokens sicher und rotieren Sie sie; validieren Sie state; überprüfen Sie den aud von ID-Tokens; verifizieren Sie Tokens bei jedem API-Aufruf (Introspektion oder JWT-Validierung) und erzwingen Sie Scopes und den Patientenkontext auf der Datenebene, da ein Token für Patient/123 niemals Patient/124 lesen darf; protokollieren Sie jeden Zugriff (Sicherheit und Identität: die Karte). SMART definiert auch Patient Access Brands, eine Möglichkeit für Apps, Benutzern anzuzeigen, mit welchen Organisationen sie sich verbinden können, und arbeitet mit SMART Health Links für patienteninitiierte Freigaben zusammen.
Wo es erforderlich ist
Die US-Patientenzugangsregeln verlangen von zertifizierten EHRs die Unterstützung von SMART App Launch und Backend Services; nationale Programme in Europa übernehmen es für den App-Zugang (die niederländische MedMij verwendet OAuth 2.0 mit gleichwertigen Konventionen); das IPS und viele Implementierungsleitfäden setzen es voraus. Siehe TEFCA und Nationale elektronische Gesundheitsakten.
In Anpheros
Die Anpheros Platform verwendet OAuth 2.0 mit PKCE für Apps und signierte JWT-Client-Authentifizierung für Backends, mit Scopes, die aus der Zustimmung der Person abgeleitet sind, und dem Patientenkontext, der bei jeder Anfrage durchgesetzt wird. Die Entwickler-Website dokumentiert Authentifizierung und das SMART on FHIR Backend-Muster für die darauf aufbauende Entwicklung.
Verwandte Seiten
- Sicherheit und Identität in Gesundheits-Apps: die Karte
- Patienten-Einwilligungsplattform
- SMART Health Links erklärt
- CDS Hooks erklärt
- FHIR-Suche erklärt
- SMART on FHIR Backend (Entwickler-Website)
- Authentifizierung (Entwickler-Website)
Quellen
- HL7 SMART App Launch (STU 2.2)
- HL7 SMART App Launch: Scopes und Launch-Kontext
- HL7 SMART App Launch: Backend Services
- IETF RFC 7636: PKCE
- IETF RFC 6749: OAuth 2.0
- OpenID Connect Core 1.0
Häufige Fragen
Ist SMART on FHIR dasselbe wie OAuth 2.0?
Es ist OAuth 2.0 und OpenID Connect mit FHIR-spezifischen Ergänzungen: Discovery, Launch-Kontext, die Scope-Syntax und Backend-Dienste. Jede OAuth-Bibliothek funktioniert; die SMART-Konventionen machen eine App portabel über FHIR-Server hinweg.
Benötige ich PKCE für eine serverseitige App?
In SMART v2 ja, für alle Clients, die den Autorisierungscode-Flow verwenden. Vertrauliche Clients fügen zusätzlich eine Client-Authentifizierung (ein Geheimnis oder ein signiertes JWT) hinzu.
Was ist der Unterschied zwischen patienten-/ und benutzer-/ scopes?
patient/ beschränkt den Zugriff auf den einzelnen Patienten im Launch-Kontext; user/ gewährt, was auch immer der authentifizierte Benutzer sehen darf, über Patienten hinweg. Patientenorientierte Apps verwenden patient/; Kliniker-Apps verwenden oft user/ mit Kontext.
Kann eine SMART-App in die Akte schreiben?
Wenn ihr die Berechtigungen zum Erstellen oder Aktualisieren (c, u) in ihren Scopes gewährt wurden und der Server dies zulässt. Viele Bereitstellungen gewähren Patienten-Apps nur Lese- und Suchzugriff und leiten Schreibvorgänge über spezifische Ressourcen wie QuestionnaireResponse weiter.
Kostenlos in der Sandbox testen
Ihr erster FHIR-Aufruf in 5 Minuten. Eine HL7 FHIR R4 API mit der Zustimmung des Patienten: probieren Sie sie in der Sandbox aus und verbinden Sie dann Ihre eigene App oder Ihr Kliniksystem.
Kostenlos · 30 synthetische Patienten · keine Karte
Anpheros entwickelt eine Patientenakte, die der Patient kontrolliert und mit jeder Klinik teilen kann, auf einer HL7 FHIR R4-Plattform mit Sitz in der EU. Diese Anleitungen helfen Ihnen, Ihre Gesundheit zu verstehen und zu organisieren; sie ersetzen nicht Ihren Arzt.
Über Anpheros →