--- { "title": "Token Introspection in FHIR: Ein vollständiger Leitfaden zur modernen Token-Validierung", "description": "Token Introspection ist die entscheidende Brücke zwischen Authentifizierung und Autorisierung. Wenn ein Client ein Token vorlegt, um auf FHIR-Ressourcen zuzugreifen, muss der Server prüfen, ob das Token gültig ist.", "date": "2025-08-19", "author": "Rostislav Antonov", "reading-time": "8 min", "tags": [ "Infrastructure", "Compliance" ] } --- ## 1. Authentifizierung, Autorisierung und Token Introspection In der Welt der API-Sicherheit arbeiten zwei grundlegende Konzepte zusammen, um Ressourcen zu schützen: **Authentifizierung** und **Autorisierung**. **Authentifizierung** beantwortet die Frage „Wer sind Sie?" Sie ist der Prozess der Identitätsverifizierung, der bestätigt, dass Benutzer tatsächlich die sind, die sie behaupten zu sein. Dies geschieht typischerweise bei Ihrem Identity Provider (IdP), wenn sich Benutzer mit Anmeldedaten, Biometrie oder anderen Faktoren anmelden. Das Ergebnis ist ein Token, das die authentifizierte Identität repräsentiert. **Autorisierung** beantwortet die Frage „Was dürfen Sie tun?" Sobald die Identität festgestellt ist, bestimmt die Autorisierung, auf welche Ressourcen der authentifizierte Benutzer zugreifen kann und welche Operationen er durchführen darf. In FHIR-Servern kommen hier AccessPolicy-Ressourcen zum Einsatz. **Token Introspection** ist die entscheidende Brücke zwischen diesen beiden Konzepten. Wenn ein Client ein Token vorlegt, um auf FHIR-Ressourcen zuzugreifen, muss der Server prüfen, ob das Token gültig ist. Dieser Prozess gibt außerdem Aufschluss darüber, wem das Token gehört und welche Informationen es enthält, damit der Server Autorisierungsentscheidungen treffen kann. ## 2. Warum Token Introspection? Moderne digitale Ökosysteme, insbesondere im Gesundheitswesen, sind komplex. Sie bestehen häufig aus zahlreichen Anwendungen – von Patientenportalen und EHRs bis hin zu mobilen Apps für Kliniker –, die jeweils mit unterschiedlichen Identity and Access Management (IAM)-Systemen oder IdPs verbunden sein können. Wenn ein FHIR-Server in diese Architektur eingeführt wird, sollte er keine Änderung Ihrer etablierten Authentifizierungsabläufe erzwingen. Die Neugestaltung Ihres IAM-Systems für einen neuen Dienst ist kostspielig und störend. Das Ziel ist Integration, nicht Ersatz. [Der FHIR-Server](https://www.health-samurai.io/fhir-server) sollte in der Lage sein, Token zu vertrauen und zu validieren, die von diesen externen Authentifizierungssystemen ausgestellt wurden. Hier wird Token Introspection unverzichtbar. Sie ermöglicht es Ihrem FHIR-Server, als sicherer **Resource Server** zu agieren und den Authentifizierungsprozess an Ihre vertrauenswürdigen IdPs zu delegieren. Wenn ein Client ein Token vorlegt, nutzt der FHIR-Server die Introspection, um eine entscheidende Frage zu beantworten: „Ist dieses Token authentisch?" Dieser Prozess ermöglicht es dem FHIR-Server, seine Ressourcen zu schützen, ohne selbst zum IdP zu werden. ## 3. Token Introspection in Aidbox Aidbox stellt die *TokenIntrospector*-Ressource bereit, um von externen IdPs ausgestellte Token zu validieren. Sie kann zwei verschiedene Token-Arten verarbeiten: - **JWT (JSON Web Token):** Ein in sich geschlossenes Token, das Benutzerangaben enthält und signiert ist. Der TokenIntrospector verifiziert die Signatur lokal und liest die Claims – ein Roundtrip zum Auth-Server ist nicht erforderlich. - **Opakes Token.** Eine zufällig aussehende Zeichenkette ohne eingebettete Claims. Um es zu verifizieren, ruft Aidbox den `introspection_endpoint` des Ausstellers auf (gemäß [RFC 7662](https://datatracker.ietf.org/doc/html/rfc7662)) und fragt, ob das Token aktiv ist und wen es repräsentiert. Der *TokenIntrospector* validiert das Token mit der für sein Format geeigneten Methode. Danach wendet Aidbox *AccessPolicy*-Regeln an, um zu entscheiden, auf was der Anforderer zugreifen darf. ### 3.1 Opaker Token Introspection Endpoint Technisch gesehen könnte der Introspection Endpoint für jede Art von Token verwendet werden, aber er wird am häufigsten für opake Token eingesetzt, da JWT-Token in sich geschlossen sind und verschiedene Möglichkeiten bieten, lokal validiert zu werden. Aidbox implementiert den OAuth 2.0 Token Introspection Standard (RFC 7662). Wenn ein opakes Token eintrifft, stellt der *TokenIntrospector* einen HTTP-POST-Request an den konfigurierten *introspection_endpoint* und sendet das Token zur Validierung. ```javascript { "resourceType": "TokenIntrospector", "id": "opaque-example", "type": "opaque", "introspection_endpoint": { "url": "https://auth.example.com/oauth/introspect", "authorization": "Basic Y2xpZW50OnNlY3JldA==" } } ``` Der externe Authentifizierungsserver antwortet mit einem JSON-Objekt, das angibt, ob das Token aktiv ist, und enthält relevante Claims: ```javascript { "active": true, "sub": "user123", "scope": "read write", "exp": 1684567890, "client_id": "my-client" } ``` Aidbox empfängt diese Antwort und stellt die Claims den *AccessPolicy*-Ressourcen im Token-Kontext zur Verfügung. Dieser Ansatz delegiert die gesamte Token-Validierungslogik an Ihre bestehende Identitätsinfrastruktur, während Aidbox als reiner Resource Server fungiert. ### 3.2 Drei Methoden zur Validierung eines JWT Für JWT-Token bietet Aidbox drei Validierungsmethoden, die jeweils für unterschiedliche Szenarien geeignet sind. Wählen Sie basierend auf Ihren Sicherheitsanforderungen, Infrastruktureinschränkungen und betrieblichen Bedürfnissen. #### 3.2.1 Secret-basierte Validierung Die secret-basierte Validierung verwendet ein gemeinsames Geheimnis für HMAC-basierte Signaturen (HS256). Ihr IdP signiert Token mit diesem Geheimnis, und Aidbox verifiziert sie mit demselben Schlüssel. ```javascript { "resourceType": "TokenIntrospector", "id": "simple-secret", "type": "jwt", "jwt": { "iss": "https://myidp.example.com", "secret": "your-256-bit-secret-here" } } ``` Diese Methode eignet sich gut für die Entwicklung oder einfache Deployments. Sie erfordert jedoch, dass dasselbe Geheimnis sowohl in Ihrem IdP als auch in Aidbox gespeichert wird, was ein Sicherheitsproblem darstellen kann. #### 3.2.2 JWKS URI Validierung Die JWKS URI Validierung (JSON Web Key Set) ruft öffentliche Schlüssel vom bekannten Endpunkt Ihres IdPs ab. Dieser Standardansatz ermöglicht die automatische Schlüsselrotation, ohne die Aidbox-Konfiguration aktualisieren zu müssen. ```javascript { "resourceType": "TokenIntrospector", "id": "jwks-example", "type": "jwt", "jwt": { "iss": "https://myidp.example.com", "jwks_uri": "https://myidp.example.com/.well-known/jwks.json" } } ``` Ihr IdP veröffentlicht seine öffentlichen Schlüssel am JWKS-Endpunkt. Aidbox ruft diese Schlüssel ab und speichert sie im Cache, wobei sie automatisch aktualisiert werden, wenn sie sich ändern. Dieser Ansatz funktioniert mit standardmäßigen OAuth 2.0/OIDC-Providern und unterstützt RSA- und Elliptische-Kurven-Algorithmen wie RS256 und ES256. #### 3.2.3 Kryptografische Schlüssel (neu in Aidbox ab Version 2505) Diese Methode ermöglicht es Ihnen, mehrere kryptografische Schlüssel direkt in der *TokenIntrospector*-Konfiguration anzugeben. Sie erlaubt die explizite Schlüsselverwaltung innerhalb von Aidbox und unterstützt gleichzeitig mehrere Algorithmen und Schlüsseltypen. ```javascript { "resourceType": "TokenIntrospector", "id": "multi-key-example", "type": "jwt", "jwt": { "iss": "https://myidp.example.com", "keys": [ { "alg": "RS256", "format": "PEM", "pub": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...\n-----END PUBLIC KEY-----\n" }, { "alg": "ES256", "format": "PEM", "pub": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...\n-----END PUBLIC KEY-----\n" } ] } } ``` Diese Methode ist besonders nützlich in Umgebungen, in denen eine direkte Schlüsselverwaltung bevorzugt wird oder wenn JWKS-Endpunkte nicht verfügbar sind. ## 4. Vertiefung: Konfiguration kryptografischer Schlüssel ### 4.1 Warum mehrere Schlüssel? Die Unterstützung mehrerer Schlüssel in einem einzigen TokenIntrospector löst mehrere reale Herausforderungen: - **Schlüsselrotation**: Während einer Schlüsselrotation müssen Sie häufig sowohl alte als auch neue Schlüssel gleichzeitig unterstützen. Einige Token könnten mit dem vorherigen Schlüssel signiert sein, während neue Token den aktualisierten Schlüssel verwenden. - **Gemischte Algorithmen**: Verschiedene Anwendungen in Ihrem Ökosystem könnten unterschiedliche kryptografische Algorithmen verwenden. Mobile Apps bevorzugen möglicherweise ES256 aus Leistungsgründen, während Web-Anwendungen RS256 aus Kompatibilitätsgründen verwenden. - **Parallele IdPs**: Große Organisationen haben häufig mehrere IdPs oder Umgebungen. Ein einziger *TokenIntrospector* kann Token aus verschiedenen Quellen validieren, jede mit ihren eigenen Schlüsseln. - **Schrittweise Migration**: Beim Übergang zwischen Schlüsseltypen oder Providern können Sie neue Schlüssel hinzufügen, ohne sofort alte zu entfernen, was unterbrechungsfreie Aktualisierungen gewährleistet. ### 4.2 Unterstützte Schlüsseltypen und Formate Aidbox unterstützt folgende kryptografische Schlüssel und Algorithmen: | Schlüsseltyp ([kty](https://datatracker.ietf.org/doc/html/rfc7518#section-6.1)) | Algorithmen (alg) | Format | Schlüsselfeld | Anwendungsfall | | --- | --- | --- | --- | --- | | RSA | RS256, RS384 | PEM | pub | Breite Kompatibilität, etablierter Standard | | EC | ES256 | PEM | pub | Kleinere Schlüssel, bessere Performance | | OCT | HS256 | plain | [k](https://datatracker.ietf.org/doc/html/rfc7518#section-6.4.1) | Gemeinsame Geheimnisse, symmetrische Signierung | **Regeln zur Schlüsselkonfiguration:** - **Asymmetrische Schlüssel** (RSA, EC): Verwenden Sie das *pub*-Feld mit dem *PEM*-Format - **Symmetrische Schlüssel** (OCT): Verwenden Sie das *k*-Feld mit dem *plain*-Format - **Formatanforderungen**: *PEM* ist für asymmetrische Algorithmen obligatorisch, *plain* für symmetrische Algorithmen ### 4.3 Vollständiges JSON-Beispiel Hier ist ein umfassendes Beispiel mit vier verschiedenen Schlüsseln in einem TokenIntrospector: ```javascript { "resourceType": "TokenIntrospector", "id": "comprehensive-keys", "type": "jwt", "jwt": { "iss": "https://myidp.example.com", "keys": [ { "kty": "RSA", "alg": "RS256", "format": "PEM", "pub": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4f5wg5l2hKsTeNem/V41fGnJm6gOdrj8ym3rFkEjWT2btf0hEkNKsP8d9xwnSsWLXY0vhU7LWNBTSwJjJGrQ6cOq5m4eUzjbRpLo8Oez7UyO8vRrGI7w2E1+BZrFf6rZ0KS8yDJ8nKnEWP+a5CKJmLkZqzZ8oVMODbqPG6fOj8+qr5VZ6jJ7XzB9W8qR2s7LQ+5t9W8vq2XZ4gPw5Vp9X7+Wz6B+o8C3k7Q3g+t8D7h9+4e7u7Bp9E+P0Q0q4g8OO7L8qO5x5D7aF3R9g+O2OP3O+D3q+t5/yb1nRO8UuE3WO0u1xZ4qP1HJE3K+Tl+vE/Pt6Cw2EPz1EOpJu6F/JO9H8XQIDAQAB\n-----END PUBLIC KEY-----\n" }, { "kty": "RSA", "alg": "RS384", "format": "PEM", "pub": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA7Z8...\n-----END PUBLIC KEY-----\n" }, { "kty": "EC", "alg": "ES256", "format": "PEM", "pub": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE4f5wg5l2hKsTeNem/V41fGnJm6gOdrj8ym3rFkEjWT2btf0hEkNKsP8d9xwnSsWLXY0vhU7LWNBTSwJjJGrQ==\n-----END PUBLIC KEY-----\n" }, { "kty": "OCT", "alg": "HS256", "format": "plain", "k": "your-256-bit-secret-key-here-must-be-long-enough" } ] } } ``` ### 4.4 Wie Aidbox den richtigen Schlüssel auswählt Bei der Validierung eines JWT folgt Aidbox einem spezifischen Algorithmus zur Auswahl des geeigneten Schlüssels: - **Algorithmus-Abgleich**: Aidbox extrahiert den *alg*-Claim aus dem JWT-Header und sucht nach Schlüsseln mit übereinstimmenden Algorithmen. - **Sequenzielles Testen**: Aidbox testet jeden Schlüssel mit übereinstimmendem Algorithmus zusammen mit der Überprüfung des Schlüsselformats und des kty (Schlüsseltyps), bis einer die Signatur erfolgreich validiert. Dieser Ansatz stellt sicher, dass Token korrekt validiert werden, auch wenn eine Schlüsselrotation im Gange ist oder mehrere Algorithmen im Einsatz sind. ### 4.5 Häufige Fehler, die es zu vermeiden gilt **Falsches Format**: Der häufigste Fehler ist die Nichtübereinstimmung des Format-Feldes mit der tatsächlichen Schlüsselkodierung. PEM-Schlüssel müssen Header und ordnungsgemäße Zeilenumbrüche enthalten, während das plain-Format das rohe Schlüsselmaterial erwartet. **Fehlender Aussteller**: Das Vergessen, das Feld `jwt.iss` zu setzen, bedeutet, dass Token diesem TokenIntrospector nicht zugeordnet werden können, was zu Validierungsfehlern führt. **Algorithmus-Nichtübereinstimmung**: Die Verwendung von `alg: "RS256"` mit einem Elliptische-Kurven-Schlüssel oder die Angabe von ES256 mit einem RSA-Schlüssel führt zu kryptografischen Fehlern. **Falsche Schlüsselkodierung**: Base64-Kodierungsprobleme kommen häufig bei Schlüsseln im plain-Format vor. Stellen Sie sicher, dass Ihr Schlüsselmaterial korrekt kodiert ist. ## 5. AccessPolicy-Beispiel Die Token-Validierung bestätigt lediglich, dass ein JWT legitim ist – sie bestimmt nicht, auf was der Benutzer zugreifen kann. Dafür sind AccessPolicy-Ressourcen zuständig. Nach erfolgreicher Token-Validierung extrahiert Aidbox Claims aus dem JWT und stellt sie für Autorisierungsentscheidungen bereit. Eine einfache AccessPolicy könnte wie folgt aussehen: ```javascript { "id": "external-auth-server", "engine": "json-schema", "schema": { "required": [ "jwt" ], "properties": { "jwt": { "required": [ "iss" ], "properties": { "iss": { "constant": "https://auth.example.com" } } } } } } ``` Diese Richtlinie stellt sicher, dass nur Token mit dem richtigen Aussteller auf Ressourcen zugreifen können. Sie können ausgefeiltere Richtlinien basierend auf Benutzerrollen, Scopes oder anderen JWT-Claims erstellen. Beachten Sie: **Validierung ≠ Autorisierung**. Ein gültiges Token gewährt nicht automatisch Zugriff – Ihre AccessPolicies bestimmen, was jeder Benutzer tun darf. ## 6. Best Practices und Tipps für Token Introspection **Schlüssel regelmäßig rotieren**: Implementieren Sie einen Schlüsselrotationsplan, insbesondere für Produktionsumgebungen. Verwenden Sie die Mehrschlüssel-Funktion, um eine nahtlose Rotation zu ermöglichen. **Asymmetrische Algorithmen bevorzugen**: Verwenden Sie wenn möglich RS256 oder ES256 anstelle von HS256. Asymmetrische Schlüssel eliminieren die Notwendigkeit, Geheimnisse zwischen Systemen auszutauschen. **Aussteller-Claims konsistent halten**: Stellen Sie sicher, dass Ihr IdP in allen Token stets denselben `iss`-Wert verwendet. Eine Änderung der Aussteller erfordert die Aktualisierung der TokenIntrospector-Konfigurationen. **Umgebungsspezifische Introspektoren verwenden**: [Erstellen Sie separate](https://www.health-samurai.io/docs/aidbox/configuration/init-bundle) TokenIntrospector-Ressourcen für Entwicklungs-, Staging- und Produktionsumgebungen. Dies verhindert die umgebungsübergreifende Token-Akzeptanz. **Ablauf von Schlüsseln überwachen**: Verfolgen Sie, wann Ihre kryptografischen Schlüssel ablaufen, und planen Sie die Rotation entsprechend. Abgelaufene Schlüssel führen zu Validierungsfehlern. ## 7. Nächste Schritte für Ihre FHIR-Sicherheit Der Aidbox TokenIntrospector bietet umfassende Token-Validierungsoptionen für Ihre FHIR-Infrastruktur. Ob Sie sich für opake Token-Introspection, secret-basierte Validierung, JWKS URI oder direkte kryptografische Schlüsselkonfiguration entscheiden – jede Methode bietet unterschiedliche Vorteile für verschiedene Anwendungsfälle und architektonische Anforderungen. Durch die gleichzeitige Unterstützung mehrerer Validierungsansätze und Schlüsseltypen ermöglicht Aidbox die Implementierung robuster Sicherheitspraktiken, die mit Ihrer bestehenden Identitätsinfrastruktur und Ihren betrieblichen Anforderungen übereinstimmen. Suchen Sie nach einem FHIR-Server, der mit Ihrem aktuellen Authentifizierungs-Setup zusammenarbeitet? In Aidbox ist Token Introspection bereits integriert. [Probieren Sie es noch heute aus](https://www.health-samurai.io/fhir-server) und sehen Sie, wie es in Ihr System passt. Siehe auch: [RBAC mit Keycloak und SMART on FHIR V2](/blog/implementing-role-based-access-control-for-fhir-resources-with-keycloak-and-smart-on-fhir-v2) und [Verwendung eines API-Gateways mit FHIR](/blog/using-api-gateway-with-fhir-api).