MAIERZONE PUBLISHER · REPORT

Keycloak 26 — Ops & Hardening Report

Sicherer Produktivbetrieb von Keycloak 26.x: Architektur, Härtungs-Best-Practices und eine eigene Sektion für bekannte Hindernisse & Probleme. Stand: 26.7.2.

Version
26.7.2
Stand
2026-08-21
Scope
Ops & Hardening
Laufzeit
OpenJDK 21 (Java 25 unterstützt)
EXECUTIVE SUMMARY

Die drei Hebel für sicheren Betrieb

Keycloak 26 ist die aktuelle Major-Linie des Open-Source-Identity-Providers (CNCF-Inkubation). Für den Betrieb entscheiden drei Dinge: eine saubere Reverse-Proxy-/TLS-Schicht, die strikte Trennung von Main- und Management-Port sowie disziplinierte Token-/Session-Härtung (DPoP, FAPI 2, Passkeys).

Die 26.x-Linie liefert kontinuierlich Sicherheitsverbesserungen — aber eben auch eine auffällig lange Reihe von Breaking Changes in Patch-Releases (26.6.x, 26.7.x). Ein Upgrade ohne den Upgrading-Guide ist daher riskant. Die folgende Kennzahl-Übersicht fasst den Betriebs-Fokus zusammen.

Patch-Stand
26.7.2
aktuelle 26.x-Linie
Java-Laufzeit
21/25
Container: OpenJDK 21
Security-Profil
FAPI 2
Final + DPoP supported
Ports
2
Main & Management trennen
EINORDNUNG

Was ist Keycloak 26?

Keycloak ist der zentrale Identity- & Access-Management-Baustein: SSO, Identity Brokering, User Federation (LDAP/AD), OAuth 2.0, OIDC und SAML. Die Linie 26 begann mit 26.0 und steht aktuell auf 26.7.2. Der Server-Container läuft standardmäßig auf OpenJDK 21; Java 25 wird ab 26.6 unterstützt (der Container bleibt aus FIPS-Gründen bei 21).

Die sicherheitsrelevanten Meilensteine der Linie: Passkeys, FAPI 2 Final und DPoP wurden in 26.4 „supported“; Zero-Downtime Patch Releases und der JWT Authorization Grant (RFC 7523) in 26.6; Multi-Cluster v2 (HA ohne externes Infinispan) und SCIM kamen in 26.7 als Preview hinzu. Parallel dazu werden schwache Defaults aktiv abgebaut — AES-Schlüssel steigen auf 256 Bit, Session-Cookies wechseln auf SHA-384, SHA-1 wird in 27 entfernt.

KOMPONENTEN

Architektur & Betrieb

Der Härtungs-Chokepoint ist der Reverse Proxy: er terminiert TLS und reicht Zertifikats-Informationen korrekt weiter. Dahinter läuft Keycloak auf dem Main-Port (8080); Health-/Metrik-Endpunkte liegen auf dem getrennten Management-Port (9000), der nicht über den Proxy exponiert werden darf. Persistenz kommt aus PostgreSQL, Caches aus eingebettetem Infinispan, externe Identitäten aus LDAP/AD oder föderierten IdPs.

Keycloak 26 — Komponenten & Vertrauensgrenzen Härtungs-Chokepoints: TLS-Terminierung am Proxy, getrennter Management-Port Trusted Server Zone HTTPS 8080 JDBC Infinispan Federation Brokering OTLP Client / App OIDC · OAuth 2.0 Reverse Proxy TLS-Terminierung Keycloak Main :8080 PostgreSQL JDBC Infinispan embedded LDAP / Active Directory Federation Externer IdP SAML · OIDC OpenTelemetry OTLP
Abb. 1: Komponenten und Vertrauensgrenzen eines Keycloak-26-Produktivbetriebs.

Betriebs-Leitplanken

HOCHVERFÜGBARKEIT

Multi-Cluster v2 statt externem Infinispan

Das klassische Multi-Site-Setup benötigt einen externen Infinispan-Cluster plus vendor-spezifisches Fencing — erhebliche Betriebskomplexität. Multi-Cluster v2 (26.7, Preview) entfernt diese Abhängigkeit: Die Knoten verbinden sich direkt über eingebettete Caches, die synchron replizierte Datenbank ist die Single Source of Truth, und die Cache-Invalidierung läuft über einen DB-gestützten Outbox. Für Rolling Updates gilt weiterhin: immer ein Knoten nach dem anderen.

Multi-Cluster v2 — HA ohne externes Infinispan PostgreSQL als Single Source of Truth, Invalidierung via DB-Outbox Cluster (stateless) HTTPS HTTPS Cache-Mesh JDBC JDBC Reverse Proxy / LB Sticky Sessions Keycloak Site A Keycloak Site B PostgreSQL synchron repliziert
Abb. 2: Multi-Cluster v2 — zwei stateless Sites, eine synchron replizierte Datenbank.
TOKEN-SICHERHEIT

Auth- & Token-Flows: PKCE + DPoP

Für Browser-Apps ist der Authorization Code Flow mit PKCE der Standard. DPoP (seit 26.4 supported) macht Tokens sender-constrained: Jeder Token-/API-Aufruf trägt einen kryptografischen Proof, sodass ein gestohlenes Token ohne den privaten Schlüssel wertlos ist. Für Hochsicherheits-Clients erzwingt FAPI 2 zusätzlich HTTPS-Endpunkte und DPoP-gebundene Tokens.

OIDC Authorization Code + PKCE + DPoP Sender-constrained Tokens: DPoP-Proof an Token- und API-Aufrufen Browser (Client) Keycloak App-Backend (RS) Authorize Redirect Token Tokens API-Call Introspect Response Browser (Client) SPA Keycloak Auth-Server App-Backend (RS) API
Abb. 3: Authorization Code + PKCE mit DPoP-gebundenen Access-/Refresh-Tokens.

Beachte: Lightweight Access Tokens sind für die Introspection gedacht — der UserInfo-Endpunkt lehnt sie seit 26.6.2 ab. Die Token-Introspection prüft seit 26.6.2 zudem, dass der aufrufende Client im aud-Claim steht.

HÄRTUNG

Best Practices im Überblick

Die folgende Checkliste trennt MUST (nicht verhandelbar) von SHOULD (situativ). Jeder Punkt ist gegen die Keycloak-26-Dokumentation und die 26.4–26.7 Release-/Upgrading-Notes gehalten.

  1. H1MUST
    TLS endet am Proxy, nicht an Keycloak. Zertifikats-Weiterleitung korrekt konfigurieren; der Reverse Proxy ist die erste Verteidigungslinie und wird für alle Host-Header/Forwarding-Fragen maßgeblich.
  2. H2MUST
    Management-Port getrennt halten. Health-/Metrik-Endpunkte (9000) niemals öffentlich exponieren; am Proxy den Zugriff auf /health explizit blocken.
  3. H3MUST
    Redirect-URIs exakt, ohne Wildcards. Seit 26.6.3 greifen Hostname-Wildcards (https://example.com*) nicht mehr wie früher — OAuth-BCP und OAuth 2.1 verlangen ohnehin exakten String-Abgleich.
  4. H4MUST
    Tokens sender-constrainen. DPoP für öffentliche Clients aktivieren, um Token-Diebstahl zu entschärfen; Refresh-Tokens von Public Clients zwingend DPoP-binden.
  5. H5MUST
    FAPI 2 für Hochsicherheits-Clients. Für Finanz-/regulierte Kontexte die Client-Profile fapi-2-* erzwingen; DPoP-Variante für sender-constrained.
  6. H6MUST
    Passkeys / WebAuthn statt Passwörtern. WebAuthn-Policy mit Discoverable Credential (required/preferred/discouraged) statt des deprecated Yes/No-Schalters.
  7. H7SHOULD
    Keine statischen Client-Secrets. Vault-SPI für Secrets nutzen; für Services Federated Client Auth (SPIFFE/K8s-Service-Account-Tokens) oder JWT Authorization Grant (RFC 7523) statt gehorteter Secrets.
  8. H8SHOULD
    Observability aktivieren. OpenTelemetry (Traces, Logs, Metriken), MDC-Logging und dedizierte HTTP-Access-Logs ohne Token-Leakage für Audit-/Compliance.
  9. H9SHOULD
    Secrets literal injizieren. Bei Passwörtern/Secrets mit $-Zeichen das KCRAW_-Prefix nutzen, damit Werte nicht als Ausdrücke evaluiert werden.
  10. H10SHOULD
    DB & Keys pflegen. Backups, UTF-8-Encoding, PostgreSQL Async-Commit (26.7) bewusst steuern; Realm-Keys auf AES-256 migrieren, bevor Sessions mit alten 128-Bit-Keys ablaufen.
BEKANNTE PROBLEME

Hindernisse & bekannte Probleme

Der größte Stolperstein der 26.x-Linie ist nicht ein einzelner Bug, sondern die Dichte an Breaking Changes in Patch-Releases. Wer 26.6.0 → 26.7.2 blind aktualisiert, trifft auf geänderte Introspection-, UserInfo-, Redirect- und mTLS-Semantik. Die Matrix unten priorisiert nach Betriebs-Risiko.

ProblemSeitRisikoMitigation
Introspection prüft aud-Claim26.6.2hochIntrospizierenden Client per Audience-Mapper ins aud aufnehmen oder Kompatibilitäts-Flag (deprecated) bis zur Korrektur.
UserInfo lehnt Lightweight Access Tokens ab26.6.2hochIntrospection statt UserInfo, oder Token Exchange zu vollem Token.
Hostname-Wildcards in Redirect-URIs entfallen26.6.3hochRedirect-URIs exakt pflegen; https://* bleibt erlaubt, alles andere wird wie /* behandelt.
X509-Client-Auth verlangt CA Subject DN26.7.0mittelCA-Subject-DN setzen; bei TLS-terminierendem Proxy Trust-/mTLS-Store korrekt konfigurieren.
Outgoing HTTP folgt Redirects nicht mehr26.6.1mittelBroker-/IdP-Endpunkte prüfen; Flag --spi-connections-http-client--default--allow-redirects nur übergangsweise.
JS-Policies brauchen scripts-Feature26.6.0mittel--features=scripts explizit aktivieren, falls JS-Policies genutzt werden.
view-system-Admin-Rolle entfernt26.7.0mittelAuf Master-Realm-User mit manage-realm umstellen; vor Upgrade Zugriffe prüfen.
IdP-Alias unveränderlich26.7.0niedrigAlias nur noch bei Anlage setzen; REST-Alias-Updates liefern 400.
DPoP nicht für implicit/hybrid26.7.0niedrigNur Authorization-Code-Flow verwenden; implicit/hybrid sind ohnehin deprecated.
SHA-1 wird entfernt27 (angekündigt)niedrigBereits jetzt auf SHA-2/SHA-3 umstellen.

Sicherheits-Trajektorie der 26.x-Linie

  1. 26.4.0
    Passkeys, FAPI 2 Final und DPoP werden „supported“ — der größte Token-Sicherheits-Schub der Linie.
  2. 26.4.6
    LDAP-Referrals werden standardmäßig gefiltert (Best-Practice-Härtung).
  3. 26.5.0
    OpenTelemetry Logs/Metriken, MDC-Logging supported; Outgoing-HTTP-Retry bleibt standardmäßig aus.
  4. 26.6.0
    Federated Client Auth und JWT Authorization Grant supported; Zero-Downtime Patch Releases werden Standard.
  5. 26.7.0
    Multi-Cluster v2 und SCIM als Preview; AES-256-/SHA-384-Defaults; mehrere Breaking Changes.
  6. 26.7.2
    Aktueller Patch-Stand; Legacy-Account-Linking-Endpoint standardmäßig deaktiviert.
supported preview experimental
UPGRADE

Migration 25 → 26 Kurz-Checkliste

  1. M1SCHRITT
    Vor jedem Minor/Patch-Update den Upgrading-Guide lesen — die 26.x-Linie führt Breaking Changes auch in Patches ein.
  2. M2SCHRITT
    Redirect-URIs, Introspection-Clients (aud), UserInfo-Nutzung und JS-Policies gegen die Breaking-Change-Matrix prüfen.
  3. M3SCHRITT
    Clustered-Updates strikt ein Knoten nach dem anderen; Zero-Downtime Patch Releases nur innerhalb desselben Minor-Streams.
  4. M4SCHRITT
    Nach dem Upgrade Realm-Keys auf AES-256 nachziehen und abgelaufene Sessions mit alten Keys auslaufen lassen.
PostgreSQL Async-Commit (26.7) — was zu beachten ist
Transaktionen auf flüchtigen Tabellen (User-/Client-Sessions, Login-Failures, Events) nutzen seit 26.7 PostgreSQL Async Commit; Logouts erzwingen weiterhin synchronen Commit. Wer strikte Dauerhaftigkeit dieser Tabellen braucht, deaktiviert es mit --spi-connections-jpa--quarkus--async-commit=false.
VERIFIKATION

Quellen

Alle Aussagen sind gegen die offizielle Keycloak-Dokumentation (Stand 26.7.2) geprüft.