Try it free in the sandbox · first FHIR call in 5 minutesFree · 30 synthetic patients · no card

Patientenzustimmung mit SMART on FHIR implementieren

Q: Benötige ich PKCE?

Ja. Anpheros erfordert PKCE mit S256 für jeden Autorisierungscode-Flow, sowohl für öffentliche als auch für vertrauliche Clients. Es verhindert, dass ein abgefangener Autorisierungscode von jemand anderem verwendet wird.

Q: Was passiert, wenn die Person "Nein" sagt?

Sie kehrt zu Ihrer Redirect URI mit error=access_denied und Ihrem state zurück, aber ohne Code. Erklären Sie, was die Funktion benötigt, und lassen Sie sie es erneut versuchen. Aufrufe außerhalb einer Berechtigung beantworten immer 403.

Tutorial: SMART on FHIR mit OAuth 2.1 und PKCE Schritt für Schritt – Discovery, App-Registrierung, Zustimmungsbildschirm, Token-Austausch, durchgesetzte Scopes, Refresh-Rotation und Widerruf – und was Anpheros implementiert.

SMART on FHIR ist der Standardweg, wie eine Anwendung die Erlaubnis einer Person erhält, auf deren FHIR-Datensatz zuzugreifen: OAuth 2.1 mit PKCE für die Autorisierung, Scopes, die genau angeben, was gelesen oder geschrieben werden darf, und ein Discovery-Dokument, das der Anwendung mitteilt, wohin sie gehen soll. Dieses Tutorial durchläuft den gesamten Ablauf gegen Anpheros, Schritt für Schritt mit curl: Discovery, Registrierung einer Anwendung, Weiterleitung der Person zum Einwilligungsbildschirm, Austausch des Codes, Aufruf der API innerhalb der gewährten Scopes, Refresh und was passiert, wenn die Person den Zugriff widerruft. Anpheros ist das SMART on FHIR Backend: Es hostet den Autorisierungsserver, den Einwilligungsbildschirm und den FHIR R4 Server, sodass Sie keine eigene Login- oder Einwilligungs-UI schreiben müssen.

Warum Einwilligung und nicht nur ein API-Schlüssel

Ein API-Schlüssel erreicht die Patienten, die Ihr Projekt erstellt hat. Die vorhandenen Aufzeichnungen einer Person (ihre eigenen Daten, gesammelt von anderen Apps, Kliniken und Laboren) kann sie selbst teilen. Mit SMART on FHIR:

sieht die Person in ihrer Sprache, welche Anwendung fragt, was sie lesen oder schreiben möchte, zu welchem Zweck und wie lange;
Ihre Anwendung erhält nur diese Ressourcentypen und Aktionen, und nur für diesen einen Datensatz;
jeder Zugriff wird protokolliert und ist für die Person sichtbar, die ihn jederzeit widerrufen kann;
die Erlaubnis wird auch als FHIR Consent Ressource gespeichert.

Das zugrunde liegende Modell wird in Healthcare API mit Patienteneinwilligung und Einwilligungs- und Zugriffsmodell beschrieben.

Schritt 1: Discovery

curl https://platform.anpheros.com/fhir/R4/.well-known/smart-configuration

Die Antwort listet die Endpunkte auf und was der Server unterstützt (gekürzt):

{"issuer": "https://platform.anpheros.com",
 "authorization_endpoint": "https://platform.anpheros.com/oauth/authorize",
 "token_endpoint": "https://platform.anpheros.com/oauth/token",
 "revocation_endpoint": "https://platform.anpheros.com/oauth/revoke",
 "code_challenge_methods_supported": ["S256"],
 "scopes_supported": ["patient/*.rs", "patient/Patient.r", "patient/Observation.rs", "patient/Observation.rs?category=laboratory",
                      "patient/Observation.rs?category=vital-signs", "patient/Observation.c", "patient/Condition.rs",
                      "patient/MedicationStatement.rs", "patient/DocumentReference.rs", "patient/AllergyIntolerance.rs",
                      "offline_access", "launch/patient", "openid", "fhirUser"],
 "capabilities": ["launch-standalone", "client-public", "client-confidential-symmetric", "permission-patient",
                  "permission-offline", "context-standalone-patient", "sso-openid-connect"]}

SMART-Clientbibliotheken lesen dieses Dokument und benötigen keine weitere Konfiguration.

Schritt 2: Registrieren Sie Ihre Anwendung

Öffnen Sie in Ihrem Dashboard Ihr Projekt und fügen Sie eine Anwendung mit ihrer Redirect URI hinzu. Oder über die Admin API:

curl -X POST https://platform.anpheros.com/admin/projects/$PROJECT/applications \
     -H "Authorization: Bearer $FIREBASE_ID_TOKEN" -H "Content-Type: application/json" -d '{
  "name": "CardioAI", "client_type": "public",
  "redirect_uris": ["https://cardio.example/callback"],
  "purpose": "cardiology follow-up", "privacy_url": "https://cardio.example/privacy"
}'

{"id": "app_…", "name": "CardioAI", "client_type": "public", "client_id": "client_Hg6CknNkYlMgN190", "client_secret": null,
 "redirect_uris": ["https://cardio.example/callback"], "purpose": "cardiology follow-up", "status": "active", …}

Verwenden Sie public für mobile und Browser-Apps, die kein Secret speichern können und auf PKCE angewiesen sind. Verwenden Sie confidential für einen Server; dessen client_secret wird einmal angezeigt. Der Name, der Zweck und der Link zur Datenschutzerklärung sind das, was die Person auf dem Zustimmungsbildschirm sieht.

Schritt 3: Senden Sie die Person zum Zustimmungsbildschirm

Erstellen Sie ein PKCE-Paar. Der Verifier bleibt bei Ihnen; nur sein Hash wird übertragen:

VERIFIER=$(openssl rand -base64 64 | tr -d '=+/\n' | cut -c1-64)
CHALLENGE=$(printf %s "$VERIFIER" | openssl dgst -sha256 -binary | openssl base64 | tr '+/' '-_' | tr -d '=')

Öffnen Sie dann diese Adresse im Browser der Person (Zeilenumbrüche zur besseren Lesbarkeit hinzugefügt):

https://platform.anpheros.com/oauth/authorize?response_type=code
  &client_id=client_Hg6CknNkYlMgN190
  &redirect_uri=https://cardio.example/callback
  &scope=openid fhirUser patient/Observation.rs?category=laboratory patient/Condition.rs offline_access
  &state=8c1e…               ← a random value you check on return
  &code_challenge=$CHALLENGE&code_challenge_method=S256
  &purpose=treatment&lang=en

Fragen Sie nur nach dem Nötigsten. Diese Anwendung liest Laborergebnisse und Diagnosen, nichts weiter. offline_access gibt ein Refresh-Token, sodass die Person nicht alle 30 Minuten erneut zustimmen muss.

Die Person meldet sich bei Anpheros an, liest die Anfrage in Klartext, wählt aus, welche Aufzeichnung sie teilen möchte (ihre eigene, die eines Familienmitglieds, für das sie sorgt, oder die, die Ihre App für sie erstellt hat) und wie lange der Zugriff dauern soll, und erlaubt oder verweigert dann. Sie kehrt zu Ihrer Redirect URI zurück:

https://cardio.example/callback?code=…&state=8c1e…

Überprüfen Sie, ob state der Wert ist, den Sie zuvor gesendet haben, bevor Sie den Code verwenden.

Schritt 4: Code gegen Tokens austauschen

curl -X POST https://platform.anpheros.com/oauth/token \
  -d grant_type=authorization_code -d client_id=client_Hg6CknNkYlMgN190 \
  -d code=$CODE -d code_verifier=$VERIFIER -d redirect_uri=https://cardio.example/callback

{"access_token": "at_…", "token_type": "Bearer", "expires_in": 1800,
 "scope": "patient/Observation.rs?category=laboratory patient/Condition.rs openid fhirUser offline_access",
 "patient": "82bfd321-6a4d-4aea-943a-a62f4d81d419", "grant_id": "grant_…",
 "id_token": "eyJ…", "refresh_token": "rt_…"}

scope listet auf, was gewährt wurde. Behalten Sie dies mit den Tokens bei und zeigen Sie nur die abgedeckten Funktionen an.
patient ist die ID des Datensatzes für Ihre Anwendung. Sie ist paarweise: Eine andere Anwendung sieht dieselbe Person unter einer anderen ID.
id_token ist ein OpenID Connect-Token, dessen fhirUser-Claim die Patientenressource benennt.
Der Code funktioniert einmal und nur mit dem passenden code_verifier.

Schritt 5: API innerhalb der Scopes aufrufen

curl "https://platform.anpheros.com/fhir/R4/Observation?patient=$PATIENT&category=laboratory" -H "Authorization: Bearer $ACCESS_TOKEN"

Laborergebnisse kommen wie gewohnt zurück. Fragen Sie nach etwas außerhalb der Berechtigung, wie z. B. Medikamenten:

curl "https://platform.anpheros.com/fhir/R4/MedicationStatement?patient=$PATIENT" -H "Authorization: Bearer $ACCESS_TOKEN"

{"resourceType": "OperationOutcome", "issue": [{"severity": "error", "code": "forbidden",
  "diagnostics": "The consent behind this token does not allow 's' on MedicationStatement."}]}

Das ist ein 403. Suchen innerhalb der Berechtigung werden ebenfalls gefiltert: mit Observation.rs?category=laboratory gibt eine Suche nach allen Beobachtungen nur Laborergebnisse zurück. Jeder andere Patient existiert für dieses Token nicht (404). Die REST-Ansicht (/v1) und die Kontext-API wenden dieselben Scopes an.

Schritt 6: Aktualisieren

Zugriffstoken sind 30 Minuten gültig. Aktualisierungstoken sind 30 Tage gültig und werden bei jeder Verwendung rotiert:

curl -X POST https://platform.anpheros.com/oauth/token \
  -d grant_type=refresh_token -d client_id=client_Hg6CknNkYlMgN190 -d refresh_token=$REFRESH_TOKEN

Sie erhalten ein neues Zugriffstoken und ein neues Aktualisierungstoken. Speichern Sie das neue sofort. Die Wiederverwendung eines alten Aktualisierungstokens wird als Diebstahl behandelt: es schlägt mit 400 fehl und widerruft die gesamte Berechtigung.

Schritt 7: Widerruf

Die Person kann Ihren Zugriff in Anpheros jederzeit widerrufen, und Sie können ihn selbst widerrufen, z. B. wenn die Verbindung in Ihrer App getrennt wird:

curl -X POST https://platform.anpheros.com/oauth/revoke -d token=$REFRESH_TOKEN -d client_id=client_Hg6CknNkYlMgN190

Von da an schlägt jeder Aufruf mit dieser Berechtigung fehl 401. Behandeln Sie dies, indem Sie der Person anzeigen, dass die Verbindung beendet wurde, und anbieten, sie erneut zu verbinden. Abonnieren Sie den consent.revoked Webhook, um dies zu erfahren, ohne auf einen fehlgeschlagenen Aufruf warten zu müssen.

Mit den SDKs

Die TypeScript- und Dart-SDKs übernehmen für Sie die Schritte 3 bis 6: OAuthFlow.authorizeUrl mit einem generierten PKCE-Paar, exchange beim Callback und automatischem Refresh mit Rotation. Vollständige Beispiele: How to build an AI healthcare app with a FHIR backend (TypeScript) und How to build a healthcare app with Flutter (Dart).

Was Anpheros implementiert

Teil von SMART	In Anpheros
Discovery	`/.well-known/smart-configuration` auf der FHIR-Basis, mit den unterstützten Endpunkten, Scopes und PKCE-Methoden
Launch	Standalone Launch (die Anwendung startet und fordert dann Zugriff an); EHR Launch aus einem klinischen System heraus wird nicht angeboten
Autorisierung	OAuth 2.1 mit PKCE erforderlich, Autorisierungscode-Flow
Scopes	SMART v2 Patient-Scopes, `patient/<Resource>.<cruds>` mit Kategorie-Filtern, plus `openid` und `fhirUser`
Identität	ein OpenID Connect `id_token`, das den Patienten als FHIR-Ressource benennt
Zustimmung	ein gehosteter Zustimmungsbildschirm in der Sprache des Patienten, mit der vom Patienten gewählten Dauer, gespiegelt als FHIR `Consent`
Tokens	30-minütige Access Tokens, rotierende 30-Tage-Refresh Tokens, die an die Zustimmung gebunden sind, Widerruf
Konformität	die Capability Statement deklariert den SMART Security Service; die Gruppe "Standalone Launch" des Inferno SMART App Launch STU2 Testkits besteht 22 von 22 Tests (Lauf vom 28. September 2026); die anderen Inferno-Gruppen und Testkits wurden nicht ausgeführt

Schreiben funktioniert genauso: Scopes (patient/Observation.c, .u, .d) erlauben Ihrer Anwendung, innerhalb des Datensatzes zu erstellen, zu aktualisieren oder zu löschen. Alles Geschriebene trägt Ihre Anwendung als Autor, Wiederholungen mit einem Idempotenzschlüssel duplizieren niemals eine Messung, und Löschungen sind "soft" und behalten die Historie (Medical data API).

Was noch nicht vorhanden ist

EHR-Start (die Anwendung, die aus einem Hospitalsystem mit einem Startkontext heraus geöffnet wird).
system/ Scopes für Backend-Dienste; Organisationen verwenden stattdessen API-Schlüssel.
Bulk Data Export ($export); $everything für einen Patienten ist verfügbar.

Diese sind zusammen mit dem Rest in Versioning und Deprecation aufgeführt, und die Capability Statement ist immer die maßgebliche Quelle.

Häufig gestellte Fragen

Was ist SMART on FHIR?

Ein offener Standard, der auf OAuth 2.0/2.1 und OpenID Connect aufbaut und definiert, wie eine Anwendung Zugriff auf einen FHIR-Datensatz anfordert, welche Scopes diesen Zugriff beschreiben und wie der Server seine Endpunkte bewirbt. Jede SMART-fähige Client-Bibliothek kann jeden SMART-fähigen Server verwenden.

Benötige ich PKCE?

Ja. Anpheros erfordert PKCE mit S256 für jeden Autorisierungscode-Flow, sowohl für öffentliche als auch für vertrauliche Clients. Es verhindert, dass ein abgefangener Autorisierungscode von jemand anderem verwendet wird.

Was passiert, wenn die Person "Nein" sagt?

Sie kehrt zu Ihrer Redirect URI mit error=access_denied und Ihrem state zurück, aber ohne Code. Erklären Sie, was die Funktion benötigt, und lassen Sie sie es erneut versuchen. Aufrufe außerhalb einer Berechtigung beantworten immer 403.

Kann ein Elternteil die Zustimmung für ein Kind geben?

Ja. Auf dem Zustimmungsbildschirm kann eine Person einen Datensatz auswählen, der ihr wichtig ist, z. B. den eines Kindes, wenn dieser mit ihrem Konto verknüpft ist. Die Berechtigung gilt nur für diesen Datensatz.