|
<< Klicken Sie, um das Inhaltsverzeichnis anzuzeigen >> Navigation: Schnittstellen > FHIR Server (+) > Anmeldung (OAuth2) |
Der FHIR Server bietet zwei OAuth2-Anmeldeverfahren an. Beide führen zum selben Bearer-Token mit identischen Zugriffsrechten.
•Client-Credentials (Variante A) ist der einfache Server-zu-Server-Weg und für die meisten Anbindungen richtig.
•Authorization-Code-Flow mit PKCE (Variante B) ist für Werkzeuge gedacht, die ihn zwingend verlangen (z. B. REDCap). Er ist nur aktiv, wenn beim Client Redirect-URLs hinterlegt sind.
Vor dem Datenzugriff holt sich der Client einen Bearer-Token vom Token-Endpunkt:
POST https://EMIL-Server:8443/fhir/token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id=klinik-meinhof&client_secret=<plain-secret>
Antwort:
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 3600
}
Der Token wird in den Folgeanfragen als HTTP-Header mitgegeben:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Tokens sind standardmäßig eine Stunde gültig und vom Server selbst signiert (HMAC-SHA-256); Drittsysteme müssen sie nicht online prüfen. Nach Ablauf antwortet der Server mit 401 und WWW-Authenticate: Bearer error="invalid_token". Holen Sie dann einen neuen Token.
client_id und client_secret dürfen statt im Body auch per HTTP-Basic-Authentifizierung übergeben werden (Authorization: Basic base64(client_id:client_secret), z. B. die Voreinstellung in Postman).
Welche Änderungen an der Client-Konfiguration einen neuen Token erfordern, steht unter Wann Änderungen wirken.
Nur verfügbar, wenn beim Client mindestens eine Redirect-URL hinterlegt ist (siehe Clients verwalten). Die Zugriffsrechte (Studie, Anonym, Consent, erlaubte ItemTypen) gelten unverändert; der Flow ändert nur die Art der Anmeldung, nicht die Berechtigung.
Das Werkzeug erzeugt ein PKCE-Paar (ein zufälliges code_verifier und daraus code_challenge = base64url(SHA256(code_verifier))) und leitet den Browser des Anwenders auf den Authorize-Endpunkt:
GET https://EMIL-Server:8443/fhir/authorize
?response_type=code
&client_id=klinik-meinhof
&redirect_uri=https://tool.example.org/callback
&scope=offline_access
&state=xyz123
&code_challenge=<base64url-hash>
&code_challenge_method=S256
Der Server prüft die Anfrage und leitet den Browser standardmäßig ohne weitere Eingabe auf die redirect_uri zurück; dabei hängt er den einmaligen Autorisierungs-Code an. Der Client weist sich erst beim anschließenden Token-Tausch per Secret und PKCE aus. So ist eine unbeaufsichtigte Verbindung möglich. Ist am Server [FHIR]AUTHCONSENT=1 gesetzt, erscheint stattdessen eine Bestätigungsseite, auf der das Client-Secret einzugeben ist. Rücksprung:
https://tool.example.org/callback?code=<code>&state=xyz123
Das Werkzeug löst den Code serverseitig (ohne Browser) am Token-Endpunkt ein und weist per code_verifier nach, dass es der ursprüngliche Anfrager ist:
POST https://EMIL-Server:8443/fhir/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code=<code>&code_verifier=<verifier>
&redirect_uri=https://tool.example.org/callback
&client_id=klinik-meinhof&client_secret=<plain-secret>
Antwort:
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "8Kf3c1...",
"scope": "offline_access"
}
Den access_token gibt das Werkzeug danach wie in Variante A als Authorization: Bearer … mit. Einen refresh_token stellt der Server nur aus, wenn der Scope offline_access angefordert wurde und Refresh-Tokens nicht abgeschaltet sind. Damit holt das Werkzeug ohne erneute Browser-Anmeldung neue Access-Tokens, z. B. für geplante Hintergrund-Abrufe. Ob der Scope mitgeschickt wird, entscheidet das Werkzeug. In REDCap muss dazu in der CDIS-/FHIR-Endpunkt-Konfiguration die persistente Verbindung bzw. der Refresh-Token aktiviert sein, sonst bleibt es bei sitzungsgebundenen Tokens ohne automatische Erneuerung.
Solange der Refresh-Token gültig ist (Standard 30 Tage), holt sich das Werkzeug damit einen neuen Access-Token, ohne den Browser-Schritt zu wiederholen:
POST https://EMIL-Server:8443/fhir/token
grant_type=refresh_token&refresh_token=<refresh_token>
&client_id=klinik-meinhof&client_secret=<plain-secret>
Die Antwort enthält einen neuen Access- und Refresh-Token; der bisherige Refresh-Token wird dabei ungültig (Rotation).
•Die redirect_uri muss bei jedem Aufruf exakt einer der beim Client hinterlegten Redirect-URLs entsprechen. Andernfalls lehnt der Server ab und leitet nicht weiter (Schutz vor Umleitungsangriffen).
•Als PKCE-Verfahren wird ausschließlich S256 akzeptiert.
•Der Autorisierungs-Code ist einmalig verwendbar und zwei Minuten gültig.
Die Laufzeiten der Tokens, das Abschalten der Refresh-Tokens und die Bestätigungsseite stellen Sie in der config.ini ein (siehe Server-Einstellungen). Welche Verfahren der Server anbietet, liefert auch die SMART-Konfiguration.