Keycloak 26.8 Upgrade: Checkliste mit Breaking Changes und CVE-Fixes

Keycloak-Upgrade mit Rückfallplan? WZ-IT prüft Ihre Konfiguration gegen die Änderungen in 26.8, testet das Upgrade auf einer Kopie und betreibt Keycloak auf Wunsch dauerhaft, siehe Keycloak bei WZ-IT. Termin vereinbaren

Keycloak 26.8.0 ist am 1. Oktober 2026 erschienen. Das Release bringt drei Sicherheitskorrekturen, hebt SCIM, Client Secret Rotation und Multi-Cluster v2 auf den Status supported und führt Token-Exchange-Delegation für KI-Agenten als Preview ein. Für den Betrieb wichtiger sind die Änderungen im Upgrade-Handbuch: Mehrere Breaking Changes betreffen Identity-Provider-Mapper, Gruppen-Claims in Autorisierungsrichtlinien, Logout über Broker und die Admin-API.

Dieser Beitrag fasst die Änderungen als Checkliste zusammen, ordnet sie nach Auswirkung auf bestehende Installationen und beschreibt den Ablauf eines Minor-Upgrades. Alle Angaben beruhen auf den Release Notes und dem Upgrade-Handbuch von Keycloak, Stand Oktober 2026.

Inhaltsverzeichnis

1. Keycloak 26.8.0 auf einen Blick
2. Sicherheitskorrekturen in 26.8.0
3. Breaking Changes vor dem Upgrade prüfen
4. Geändertes Verhalten nach dem Upgrade
5. Organizations: Identity Provider für mehrere Organisationen
6. Abkündigungen und Ende des Realm Operators
7. Neue Funktionen mit Status supported und preview
8. Upgrade-Ablauf Schritt für Schritt
9. Unser Vorgehen bei WZ-IT
10. Weiterführende Guides

Keycloak 26.8.0 auf einen Blick

Wichtig für die Planung: Keycloak unterstützt seit 26.6.0 Rolling Updates nur für Patch-Releases innerhalb derselben Minor-Version. Der Schritt von 26.7.x auf 26.8.0 erfordert laut Upgrade-Handbuch das Herunterfahren aller Knoten. Laufende Anmeldevorgänge gehen dabei verloren, Benutzer müssen sie neu starten.

Sicherheitskorrekturen in 26.8.0

Die Release Notes führen folgende Sicherheitskorrekturen auf:

Die drei Keycloak-eigenen CVEs tragen in GitHub die Priorität "important". In den Release Notes von 26.7.5 sind sie nicht aufgeführt. 26.7.5 behebt andere Lücken, darunter CVE-2026-93999 (deaktivierte Clients in der Token-Audience) und CVE-2026-89298 (Client-Secret für view-clients über Client Registration). Wer auf 26.7 bleibt, sollte 26.7.5 einspielen und die Backports der 26.8-Fixes beobachten. Zusätzlich listen die Release Notes über 80 als "Weaknesses" markierte Härtungen, vor allem in SCIM, OID4VCI und der Admin-API.

Breaking Changes vor dem Upgrade prüfen

Breaking Changes in Minor-Releases führt Keycloak nach eigener Aussage nur zur Behebung von Fehlern ein. In 26.8.0 sind es sechs Punkte, die sich direkt auf bestehende Konfigurationen auswirken können (Upgrade-Handbuch, Breaking changes):

Zusätzlich gehört CVE-2026-19608 in diese Prüfung, obwohl das Handbuch sie unter "Notable changes" führt: Gruppennamen ohne Pfad in Token-Claims werden nur noch auf Top-Level-Gruppen aufgelöst. Wer den Mapper "Group Membership" mit deaktiviertem "Full group path" nutzt und Richtlinien auf verschachtelte Gruppen bezieht, muss "Full group path" aktivieren, sonst greifen diese Richtlinien nicht mehr (Upgrade-Handbuch).

Geändertes Verhalten nach dem Upgrade

Diese Änderungen brechen keine Konfiguration, verändern aber Verhalten, Last oder Logs:

Für Installationen mit großen Session-Tabellen ist der Index-Punkt relevant: Auf PostgreSQL nutzt Keycloak CREATE INDEX CONCURRENTLY und erkennt ungültige Indizes aus früheren Abbrüchen (Upgrade-Handbuch). Bei MySQL und MariaDB im Stateless-Modus setzt Keycloak die Isolationsstufe READ COMMITTED; mit binlog_format = STATEMENT schlagen Schreibvorgänge dann fehl. Unterstützte Datenbankversionen stehen im Datenbank-Guide, für PostgreSQL sind das 14 bis 18. Wer noch PostgreSQL 14 betreibt, sollte das Supportende von PostgreSQL 14 in die Planung einbeziehen.

Organizations: Identity Provider für mehrere Organisationen

Ein Identity Provider kann in 26.8 mehreren Organisationen zugeordnet werden, die Beziehung ist von viele-zu-eins auf viele-zu-viele umgestellt (Release-Ankündigung). Die Migration läuft automatisch, ändert aber das Datenmodell:

• Bestehende Verknüpfungen werden mit Auto-Membership und Typ Managed übernommen, neue Verknüpfungen erhalten standardmäßig Unmanaged.
• Das Domain-Routing wandert vom Identity Provider zur Domain. Die bisherige Ausschlussliste entfällt, ausgeschlossene Domains werden ohne zugeordneten Identity Provider migriert.
• Einstellungen wie "Hide on login page when organization is not resolved" liegen seit 26.8 in den Einstellungen des Identity Providers auf Realm-Ebene.
• Die Admin-REST-API ersetzt das Feld organizationId in IdentityProviderRepresentation durch Organisations-Links. Skripte und Terraform-Module, die dieses Feld setzen, müssen angepasst werden.
• Mapper auf Organisationsgruppen speichern die Organisations-ID explizit; bei mehreren Organisationen ist je Organisation ein eigener Mapper nötig.

Nach dem Upgrade sollten die Reiter "Domains" und "Identity providers" jeder Organisation kontrolliert werden. Wer Organisationen für mandantenfähige Anwendungen nutzt, prüft zusätzlich, ob Realm-Importe die Link-Richtlinien korrekt setzen; Issue #53166 behebt einen Fall, in dem ein Realm-Import sie auf offene Standardwerte zurücksetzte.

Abkündigungen und Ende des Realm Operators

Keine dieser Funktionen fällt in 26.8 weg, sie sollen aber in künftigen Releases entfernt werden (Upgrade-Handbuch, Deprecated features):

Endgültig beendet ist der Keycloak Realm Operator: Er hat sein Lebensende erreicht, das Repository wird archiviert. Seine Ressourcen KeycloakRealm und KeycloakClient ersetzen KeycloakRealmImport sowie KeycloakOIDCClient und KeycloakSAMLClient, die als Preview zur Verfügung stehen (Managing Keycloak Clients).

Zur Warnung bei "Full scope allowed": Für die eingebauten Clients security-admin-console und admin-cli ist sie unterdrückt. Das Handbuch rät ausdrücklich davon ab, den Schalter dort manuell zu deaktivieren, da dies den Login in die Admin Console brechen kann.

Neue Funktionen mit Status supported und preview

Die Token-Exchange-Delegation zielt laut Release-Ankündigung auf KI-Agenten und Automatisierungen, die im Namen eines Benutzers handeln, ohne Admin-Rechte zu erhalten. Ein per Client-Delegation ausgestelltes Token gewährt keinen Zugriff auf die Admin-API, auch wenn der Client Service-Account-Credentials hat. Wer die Funktion aus 26.7 bereits testet, muss den Scope von delegation auf delegation:user umstellen und die Berechtigung über FGAP V2 neu anlegen (Token-Exchange-Dokumentation). Wie Agenten-Rechte grundsätzlich begrenzt werden, beschreibt der Beitrag zu Rechten und Freigaben für KI-Agenten.

Upgrade-Ablauf Schritt für Schritt

Der folgende Ablauf folgt dem Upgrade-Handbuch und ergänzt die Prüfpunkte aus 26.8:

Vorbereitung

1. Aktuelle Version feststellen und alle "Migrating to"-Abschnitte zwischen dieser Version und 26.8.0 lesen. Bei Sprüngen über mehrere Minor-Versionen summieren sich die Änderungen.
2. IdP-Mapper auf Zuweisungen administrativer Rollen oder Gruppen mit Admin-Rollen prüfen.
3. Protokoll-Mapper "Group Membership" und Gruppenrichtlinien auf Namen ohne Pfad prüfen.
4. Automatisierungen und delegierte Admins identifizieren, die Client-Secrets mit view-clients lesen.
5. Logout-Flows mit initiating_idp sowie X509-Authenticatoren für Benutzer prüfen.
6. Eigene Login-Themes auf Überschreibungen von social-providers.ftl und CSS für IdP-Icons prüfen.
7. Eigene Provider und Erweiterungen gegen Quarkus 3.40 neu bauen und testen; bei mehreren Persistence Units in einer persistence.xml den Hinweis zur Umbenennung auf <default> beachten.
8. Startparameter prüfen: --features=preview aktiviert stateless nicht mehr, stateless braucht --cache-embedded-cluster-name.
9. Für Operator-Installationen: Labels an Secrets für KeycloakOIDCClient setzen, Abhängigkeit vom Realm Operator ablösen.

Durchführung

10. Upgrade auf einer Kopie mit Produktionsdaten testen, inklusive Logins über jeden Identity Provider.
11. Wartungsfenster einplanen, alle Knoten der alten Version stoppen.
12. Installation (Konfiguration, Themes, Provider) und Datenbank sichern. Ein Rückweg ist nur über die Wiederherstellung beider Sicherungen möglich, da Keycloak Schemaänderungen nicht zurückrollt.
13. Neue Version bereitstellen, providers/ und themes/ übernehmen, conf/ ohne cache-ispn.xml kopieren; eigene Cache-Anpassungen auf Basis der neuen cache-ispn.xml neu anwenden.
14. Ersten Knoten starten und die Schemamigration im Log verfolgen, danach die übrigen Knoten.

Nach dem Upgrade

15. Organisationen: Domains und Identity-Provider-Verknüpfungen kontrollieren.
16. Logins, Logout über Broker, Token-Inhalte (aud, groups, resource_access) und Gruppenrichtlinien testen.
17. Log auf Abkündigungswarnungen prüfen, insbesondere "Full scope allowed", und eine Liste der betroffenen Clients anlegen.
18. Datenbanklast beobachten, da Login-Fehlversuche seit 26.8 in der Datenbank liegen; Hintergrund-Indexerstellung abwarten.
19. Client-Bibliotheken (Admin Client, Authorization Client) getrennt aktualisieren, sie werden unabhängig vom Server veröffentlicht.

Für Installationen mit Keycloak als Identity Provider für VPN oder Fernzugriff lohnt sich zusätzlich ein Test der angebundenen Dienste, etwa bei NetBird mit Authentik oder Keycloak.

Unser Vorgehen bei WZ-IT

1. Bestandsaufnahme. Version, Betriebsart (VM, Container, Kubernetes mit Operator), Datenbank, Realms, Identity Provider, Themes und eigene Provider.
2. Abgleich mit den Änderungen. Prüfung der Konfiguration gegen alle Breaking Changes und Abkündigungen zwischen Ihrer Version und 26.8, als dokumentierte Liste mit Maßnahmen.
3. Testlauf. Upgrade auf einer Kopie mit Produktionsdaten, Tests der Logins, Token-Inhalte und angebundenen Anwendungen.
4. Durchführung. Sicherung von Installation und Datenbank, Upgrade im abgestimmten Wartungsfenster, Kontrolle nach dem Start und definierter Rückfallweg.
5. Betrieb. Überwachung, Backups, Updates und Auswertung von Sicherheitsmeldungen, auf Wunsch über CVE-Monitoring. Support, Beratung und Implementierung durch WZ-IT.

Details zu Hosting, Installation und Betrieb stehen auf der Seite Keycloak bei WZ-IT.

Weiterführende Guides

• Authentik vs. Zitadel, zwei Open-Source-Identity-Provider im Vergleich zu Keycloak.
• NetBird mit Authentik oder Keycloak, SSO für ein selbst betriebenes VPN einrichten.
• PostgreSQL 14 Supportende, Upgrade-Pfade für die Datenbank unter Keycloak.
• Rechte und Freigaben für KI-Agenten, wie Agenten nur die nötigen Berechtigungen erhalten.
• Managed Open Source, Betrieb von Keycloak und weiteren Open-Source-Anwendungen durch WZ-IT.

Keycloak 26.8 einspielen, ohne Logins zu riskieren? Wir prüfen Ihre Realms gegen die Breaking Changes, testen auf einer Kopie und führen das Upgrade mit Rückfallplan durch. Termin vereinbaren

Quellen

• Keycloak, Keycloak 26.8.0 released
• Keycloak, Upgrading Guide (Migrating to 26.8.0)
• GitHub, Keycloak Release 26.8.0
• GitHub, Keycloak Release 26.7.5
• GitHub Issue #50444, CVE-2026-12388
• GitHub Issue #50618, CVE-2026-14781
• GitHub Issue #51865, CVE-2026-19608
• GitHub Issue #53074, CVE-2026-93999
• GitHub Issue #50992, Neue Identity-Provider-Buttons
• Keycloak, Migrating from multi-cluster v1 to v2
• Keycloak, Token Exchange
• Keycloak, Configuring the database
• Keycloak Operator, Realm Import
• Keycloak Operator, Managing Keycloak Clients
• GitHub, Keycloak Realm Operator