🔥 Token Introspection in FHIR: Leitfaden zur modernen Validierung

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ätsprüfung, bei dem bestätigt wird, dass Benutzer tatsächlich die Personen sind, die sie vorgeben zu sein. Dies geschieht typischerweise bei Ihrem Identity Provider (IdP), wenn Benutzer sich mit Anmeldedaten, biometrischen Merkmalen oder anderen Faktoren einloggen. Das Ergebnis ist ein Token, der 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 darf und welche Operationen er ausführen kann. In FHIR-Servern kommen hier AccessPolicy-Ressourcen ins Spiel.

Token Introspection ist die entscheidende Brücke zwischen diesen beiden Konzepten. Wenn ein Client einen Token zur Abfrage von FHIR-Ressourcen vorlegt, muss der Server prüfen, ob der Token gültig ist. Dieser Prozess legt außerdem offen, wem der Token gehört und welche Informationen er enthält, damit der Server Autorisierungsentscheidungen treffen kann.

2. Warum Token Introspection?

Moderne digitale Ökosysteme, insbesondere im Gesundheitswesen, sind komplex. Sie bestehen oft 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 an Ihren etablierten Authentifizierungsabläufen 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 sollte in der Lage sein, Tokens 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 Ressourcenserver zu agieren, indem der Authentifizierungsprozess an Ihre vertrauenswürdigen IdPs delegiert wird. Wenn ein Client einen Token vorlegt, nutzt der FHIR-Server die Introspection, um eine entscheidende Frage zu beantworten: „Ist dieser Token authentisch?" Dieser Prozess ermöglicht es dem FHIR-Server, seine Ressourcen zu schützen, ohne selbst zu einem IdP zu werden.

3. Token Introspection in Aidbox

Aidbox stellt die TokenIntrospector-Ressource zur Validierung von Tokens bereit, die von externen IdPs ausgestellt wurden. Sie kann zwei verschiedene Arten von Tokens verarbeiten:

JWT (JSON Web Token): Ein in sich geschlossener Token, der Benutzer-Claims enthält und signiert ist. Der TokenIntrospector verifiziert die Signatur lokal und liest die Claims – kein Round-Trip zum Authentifizierungsserver ist erforderlich.
Opaque Token. Eine zufällig aussehende Zeichenkette ohne eingebettete Claims. Um ihn zu verifizieren, ruft Aidbox den introspection_endpoint des Ausstellers auf (gemäß RFC 7662) und fragt, ob der Token aktiv ist und wen er repräsentiert.

TokenIntrospector validiert den Token mit der für sein Format geeigneten Methode. Danach wendet Aidbox AccessPolicy-Regeln an, um zu entscheiden, auf was der Anfordernde zugreifen darf.

3.1 Opaque-Token-Introspection-Endpunkt

Technisch gesehen könnte der Introspection Endpoint für jede Art von Token verwendet werden, aber er wird am häufigsten für Opaque Tokens eingesetzt, da JWT-Tokens 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 Opaque Token eintrifft, stellt der TokenIntrospector eine HTTP-POST-Anfrage an den konfigurierten introspection_endpoint und sendet den Token zur Validierung.

{
  "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 der Token aktiv ist, und relevante Claims enthält:

{
  "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 Ressourcenserver fungiert.

3.2 Drei Möglichkeiten zur Validierung eines JWT

Für JWT-Tokens bietet Aidbox drei Validierungsmethoden, die jeweils für unterschiedliche Szenarien geeignet sind. Wählen Sie auf Basis Ihrer Sicherheitsanforderungen, infrastrukturellen Einschränkungen und betrieblichen Bedürfnisse.

3.2.1 Geheimnis-basierte Validierung

Die geheimnis-basierte Validierung verwendet ein gemeinsames Geheimnis für HMAC-basierte Signaturen (HS256). Ihr IdP signiert Tokens mit diesem Geheimnis, und Aidbox verifiziert sie mit demselben Schlüssel.

{
  "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 Sicherheitsbedenken darstellen kann.

3.2.2 JWKS-URI-Validierung

Die JWKS-URI-Validierung (JSON Web Key Set) ruft öffentliche Schlüssel vom bekannten Endpunkt Ihres IdP ab. Dieser Standardansatz ermöglicht eine automatische Schlüsselrotation, ohne die Aidbox-Konfiguration aktualisieren zu müssen.

{
  "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 bei Änderungen automatisch aktualisiert werden. Dieser Ansatz funktioniert mit Standard-OAuth-2.0/OIDC-Providern und unterstützt RSA- und Elliptic-Curve-Algorithmen wie RS256 und ES256.

3.2.3 Kryptografische Schlüssel (Neu in Aidbox seit 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.

{
  "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 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 verschiedene 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 Tokens könnten mit dem vorherigen Schlüssel signiert sein, während neue 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 oft mehrere IdPs oder Umgebungen. Ein einzelner TokenIntrospector kann Tokens aus verschiedenen Quellen validieren, jede mit ihren eigenen Schlüsseln.
Schrittweise Migration: Beim Wechsel zwischen Schlüsseltypen oder Providern können Sie neue Schlüssel hinzufügen, ohne sofort alte zu entfernen, was unterbrechungsfreie Updates gewährleistet.

4.2 Unterstützte Schlüsseltypen und Formate

Aidbox unterstützt die folgenden kryptografischen Schlüssel und Algorithmen:

Schlüsseltyp (kty)	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	Gemeinsame Geheimnisse, symmetrische Signierung

Regeln für die Schlüsselkonfiguration:

Asymmetrische Schlüssel (RSA, EC): pub-Feld mit PEM-Format verwenden
Symmetrische Schlüssel (OCT): k-Feld mit plain-Format verwenden
Formatanforderungen: PEM ist für asymmetrische Algorithmen obligatorisch, plain für symmetrische Algorithmen

4.3 Vollständiges JSON-Beispiel

Hier ist ein umfassendes Beispiel, das vier verschiedene Schlüssel in einem TokenIntrospector zeigt:

{
  "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 Tokens korrekt validiert werden, auch wenn eine Schlüsselrotation im Gange ist oder mehrere Algorithmen verwendet werden.

4.5 Häufige Fehler, die vermieden werden sollten

Falsches Format: Der häufigste Fehler ist ein Mismatch zwischen dem Format-Feld und der tatsächlichen Schlüsselkodierung. PEM-Schlüssel müssen Header und korrekte Zeilenumbrüche enthalten, während das plain-Format das rohe Schlüsselmaterial erwartet.

Fehlender Aussteller: Wird das Feld jwt.iss nicht gesetzt, stimmen Tokens nicht mit diesem TokenIntrospector überein, was zu Validierungsfehlern führt.

Algorithmus-Mismatch: Die Verwendung von alg: "RS256" mit einem Elliptic-Curve-Schlüssel oder die Angabe von ES256 mit einem RSA-Schlüssel führt zu kryptografischen Fehlern.

Falsche Schlüsselkodierung: Base64-Kodierungsprobleme sind bei plain-Format-Schlüsseln häufig. 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 darf. Dafür sind AccessPolicy-Ressourcen zuständig.

Nach erfolgreicher Token-Validierung extrahiert Aidbox Claims aus dem JWT und stellt sie für Autorisierungsentscheidungen zur Verfügung. Eine einfache AccessPolicy könnte wie folgt aussehen:

{
  "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 Tokens mit dem korrekten Aussteller auf Ressourcen zugreifen können. Sie können ausgefeiltere Richtlinien auf Basis von Benutzerrollen, Scopes oder anderen JWT-Claims erstellen.

Denken Sie daran: Validierung ≠ Autorisierung. Ein gültiger 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. Nutzen Sie die Mehrschlüssel-Funktion für eine reibungslose Rotation.

Asymmetrische Algorithmen bevorzugen: Verwenden Sie nach Möglichkeit RS256 oder ES256 anstelle von HS256. Asymmetrische Schlüssel eliminieren die Notwendigkeit, Geheimnisse zwischen Systemen zu teilen.

Aussteller-Claims konsistent halten: Stellen Sie sicher, dass Ihr IdP stets denselben iss-Wert für alle Tokens verwendet. Eine Änderung des Ausstellers erfordert die Aktualisierung der TokenIntrospector-Konfigurationen.

Umgebungsspezifische Introspektoren verwenden: Erstellen Sie separate TokenIntrospector-Ressourcen für Entwicklungs-, Staging- und Produktionsumgebungen. Dies verhindert die umgebungsübergreifende Token-Akzeptanz.

Schlüsselablauf ü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 Opaque-Token-Introspection, geheimnis-basierte Validierung, JWKS-URI oder direkte kryptografische Schlüsselkonfiguration entscheiden – jede Methode bietet spezifische Vorteile für unterschiedliche Anwendungsfälle und architektonische Anforderungen.

Durch die gleichzeitige Unterstützung mehrerer Validierungsansätze und Schlüsseltypen ermöglicht Aidbox Ihnen die Implementierung robuster Sicherheitspraktiken, die mit Ihrer bestehenden Identitätsinfrastruktur und Ihren betrieblichen Anforderungen übereinstimmen.

Suchen Sie einen FHIR-Server, der mit Ihrem bestehenden Authentifizierungs-Setup zusammenarbeitet? Aidbox verfügt über eine integrierte Token Introspection. Probieren Sie es noch heute aus und sehen Sie, wie es in Ihr System passt.

Siehe auch: RBAC mit Keycloak und SMART on FHIR V2 und Verwendung eines API-Gateways mit FHIR.