Keycloak-Upgrades ohne Bauchschmerzen: Major-Versionen planen statt fürchten

Dein Keycloak läuft, der Login funktioniert, und trotzdem nagt es: Auf keycloak.org steht eine neuere Version als in deinem Cluster, die Release-Notes listen Abkündigungen, und niemand im Team will derjenige sein, der das Login-System anfasst. Verstehen wir. Aber Aufschieben macht Keycloak-Upgrades nicht kleiner, sondern größer. Dieser Artikel macht aus dem gefürchteten Sprung einen planbaren Prozess.

Vorab die nackten Zahlen, Stand 28. September 2026: Aktuell ist Version 26.7.4 vom 16. September 2026. Feature-Releases erscheinen im Quartalsrhythmus – 26.4.0 am 30. September 2025, 26.5.0 am 6. Januar 2026, 26.6.0 am 8. April 2026, 26.7.0 am 9. Juli 2026. Dazwischen laufen Patch-Releases im Takt von zwei bis drei Wochen: 26.7.1 bis 26.7.4 erschienen binnen sechs Wochen.

Entscheidender als die Kadenz ist die Support-Logik: Sicherheitskorrekturen erscheinen laut der Security-Policy des Projekts je nach Schweregrad in der aktuellen major.minor-Version oder erst im folgenden Release; ältere Stände erhalten keine Rückportierungen. Einen Langzeit-Support-Zweig gibt es im Community-Projekt nicht; dafür verweist Keycloak auf den kommerziellen Red Hat Build. Im Klartext: Das Wartungsfenster deiner Version endet mit dem nächsten Feature-Release, also nach rund einem Quartal.

Lass dich von der Versionszählung nicht täuschen: Seit Version 26 vom Oktober 2024 tragen die großen Sprünge Nummern wie 26.6 oder 26.7. Sie heißen Minor-Releases, bringen aber neue Funktionen und Abkündigungen wie zuvor die Major-Versionen 24 und 25. Behandle deshalb jedes 26.x-Release wie ein Major-Upgrade: Migration Changes lesen, testen, dann ausrollen.

Falls du noch in der Evaluierung steckst: Was Keycloak grundsätzlich leistet und welche Identity-Dienste es ersetzt, klärt unser Überblick Was ist Keycloak?. Hier geht es um die Zeit danach – um das Upgrade als Betriebsroutine.

Wo brechen Keycloak-Upgrades in der Praxis? Aus unseren Projekten kennen wir drei wiederkehrende Muster. Keines davon ist ein Schreckgespenst, alle drei sind mit Vorbereitung beherrschbar – aber nur, wenn du weißt, wo du hinschauen musst.

Das Login-Theme ist der häufigste Bruchpunkt: Angepasste Login-Oberflächen erweitern die FreeMarker-Templates der jeweiligen Version. Ändert ein Release Struktur oder Variablen dieser Basis-Templates, rendert dein Login falsch oder gar nicht mehr. Der offizielle Upgrade-Guide führt Themes deshalb als eigenen Migrationsschritt: Templates, Messages und Styles sind bei jedem Sprung zu prüfen.

Heikler noch sind eigene Server-Erweiterungen (SPIs): Sie docken teils an Schnittstellen an, die als intern gelten. Kompiliert der Provider gegen die neue Version nicht mehr, merkst du das früh. Ändert sich nur das Verhalten, merkst du es erst im Test – schlimmstenfalls in Produktion. Faustregel: Je mehr eigener Provider-Code, desto größer die Prüfpflicht pro Release.

Keycloak migriert das Datenbankschema standardmäßig automatisch beim ersten Start der neuen Version; alternativ erzeugst du den SQL-Migrationsplan manuell zur Prüfung. Das ist komfortabel, hat aber eine Konsequenz: Die Migration läuft nur vorwärts. Eine ältere Keycloak-Version kann mit dem migrierten Schema nicht arbeiten, ein Downgrade ist nicht vorgesehen.

Daraus folgt die erste eiserne Regel: kein Upgrade ohne frisches, geprüftes Datenbank-Backup. Nicht als Formalie, sondern als einziger belastbarer Weg zurück.

Keycloak räumt konsequent auf – gut für das Projekt, Arbeit für dich. Der größte Schnitt war der Wechsel der Server-Basis von WildFly auf Quarkus mit Version 17 im Februar 2022: eine neue Konfigurationswelt, die jedes Deployment betraf. Später traf es die projekteigenen Java-Adapter; der Node.js-Adapter ist ausweislich der Download-Seite inzwischen als deprecated markiert.

Das Muster ist verlässlich: Eine Funktion wird als veraltet markiert, läuft ein bis zwei Releases als Warnung mit und verschwindet dann. Wer jede Version mitgeht, erledigt kleine Hausaufgaben. Wer drei Releases sammelt, bekommt sie gebündelt – unter Zeitdruck.

Der Unterschied zwischen Bauchschmerzen und Routine ist ein wiederholbarer Prozess. Unserer besteht aus vier Bausteinen und folgt der Reihenfolge des offiziellen Upgrading Guide: erst die Migration Changes der Zielversion lesen, dann den Server aktualisieren, zuletzt die angebundenen Clients und Adapter.

Die Migration Changes sind dabei mehr als eine Formalie: Der Guide pflegt für jede Version ein eigenes Kapitel mit allen Verhaltensänderungen, neuen Standardwerten und gestrichenen Optionen. Zwanzig Minuten Lektüre pro Release ersparen dir die Fehlersuche im laufenden Betrieb. Wer mehrere Versionen nachholt, liest die Kapitel aller übersprungenen Releases – in Reihenfolge.

Ein Staging-System mit drei Test-Nutzern prüft nichts. Aussagekraft entsteht erst mit einer echten Kopie: Realm-Konfiguration per Export übernehmen, die Datenbank als anonymisierte Kopie der Produktion aufsetzen, dieselben Themes und SPIs deployen. Dann das Upgrade exakt so durchspielen, wie es später in Produktion laufen soll.

Wichtig dabei: die automatische Schema-Migration gegen einen produktionsgroßen Datenbestand laufen lassen, denn ihre Dauer bestimmt dein Wartungsfenster. Getestet wird anschließend, was Nutzer wirklich tun: Login, Logout, Passwort-Reset, Token-Refresh und die kritischen Flows jeder angebundenen Anwendung.

Zusätzlich zum Datenbank-Backup exportieren wir vor jedem Sprung alle Realms über die eingebaute Export-Funktion. Der Export gehört versioniert ins Git-Repository: Ein Diff nach dem Test-Upgrade zeigt schwarz auf weiß, was die Migration an deiner Konfiguration verändert hat. Und im Ernstfall lässt sich ein einzelner Realm wiederherstellen, ohne die ganze Datenbank zurückzudrehen.

Der Rollback wird vorher festgelegt, nicht im Ernstfall improvisiert. Weil die Schema-Migration nur vorwärts läuft, heißt der Pfad immer: Datenbank-Snapshot unmittelbar vor der Migration plus altes Container-Image, das griffbereit bleibt. Dazu ein definiertes Beobachtungsfenster nach dem Rollout (etwa 30 bis 60 Minuten), in dem bei Auffälligkeiten zurückgerollt wird; danach gilt: vorwärts korrigieren.

Und weil ein nie geprobter Rollback keiner ist: Der Restore-Test gehört in die Staging-Phase, nicht in die Nacht des Ernstfalls.

Für Patch-Releases innerhalb desselben Release-Streams unterstützt Keycloak Rolling Updates ohne Ausfallzeit: Das Kommando update-compatibility prüft vorab, ob alte und neue Version gleichzeitig laufen dürfen. Für Feature-Releases wie den Sprung von 26.6 auf 26.7 bleibt der sichere Weg ein Blue-Green-Vorgehen: neue Umgebung hochziehen, Smoke-Tests fahren, Traffic umschalten, alte Umgebung als Rückfallebene stehen lassen.

Ehrlicherweise: Die geteilte Datenbank bleibt der Engpass. Sobald die neue Version das Schema migriert hat, taugt die alte Umgebung nur noch zusammen mit dem Datenbank-Snapshot als Rückfallebene. Wie ein Setup aussieht, in dem solche Wechsel Betriebsalltag sind, zeigt unser Artikel Keycloak-Hosting.

Zum Kern der Sache: Warum ist Liegenlassen keine Option? Die CVE-Logik arbeitet gegen dich. Wird eine Sicherheitslücke gemeldet, erscheint der Fix in der aktuellen Version – und mit seiner Veröffentlichung ist die Lücke öffentlich dokumentiert, samt der Information, welche älteren Stände verwundbar sind. Ab diesem Moment ist deine alte Version ein beschriebenes Angriffsziel.

Das eigentliche Problem ist der Handlungsdruck: Liegt dein Cluster zwei oder drei Feature-Releases zurück, kannst du den Fix nicht isoliert einspielen, denn er existiert nur im aktuellen Stream. Aus dem aufgeschobenen Routine-Upgrade wird ein Notfall-Upgrade: alle aufgelaufenen Deprecations, Theme- und SPI-Anpassungen auf einmal, während die Lücke offen steht.

Zum Thema EOL wird es schnell konkret: Ältere Versionen wandern bei Keycloak kommentarlos ins Release-Archiv. Wer heute noch eine 24 oder 25 betreibt, läuft auf einem Stand, für den seit Oktober 2024 kein einziger Patch mehr erschienen ist – zwei Jahre dokumentierter Lücken. Solche Stände gehören nicht aktualisiert, sondern als eigenes Migrationsprojekt behandelt.

Bei einem Identity-System wiegt das doppelt: Keycloak verwaltet die Zugänge zu allen angebundenen Anwendungen. Eine kompromittierte Identitätsschicht kompromittiert nicht eine Anwendung, sondern alle gleichzeitig. Unsere Merkformel dazu: Ein aufgeschobenes Upgrade ist kein gespartes Upgrade – es ist ein ungeplantes, das sich seinen Zeitpunkt selbst aussucht.

Vorab zur Einordnung: Die folgenden Spannen sind unsere Einschätzung aus Kundenprojekten, keine offiziellen Zahlen des Keycloak-Projekts. Sie hängen fast ausschließlich am Anpassungsgrad deiner Installation, kaum an der Nutzerzahl.

Warum die Spreizung? Der Standardfall ist im Kern ein Container-Tausch mit Test. Themes und SPIs dagegen verlangen Code-Anpassung, Review und einen zweiten Testdurchlauf. Der aufgelaufene Altbestand ist deshalb so teuer, weil du die Migration Changes mehrerer Versionen nacheinander abarbeiten musst – jede mit eigenen Abkündigungen.

Die wichtigste Budget-Entscheidung ist dabei keine Summe, sondern ein Rhythmus: Plane pro Quartal ein festes Upgrade-Fenster ein, im selben Takt, in dem Releases erscheinen. Vier kleine, planbare Einsätze pro Jahr schlagen einen großen unplanbaren – schlussendlich ist der Quartalstakt die günstigste Versicherung gegen das Notfall-Szenario aus dem vorigen Abschnitt.

Was der Betrieb von Keycloak insgesamt kostet, also Aufbau, Hosting und Pflege zusammengerechnet, schlüsseln wir in Was kostet Keycloak? auf.

Wenn dein Keycloak mehr als ein Release zurückliegt, beginne mit einer Bestandsaufnahme: Welche Version läuft, welche Themes und SPIs existieren, welche Migration Changes liegen zwischen dir und 26.7.4? Aus dieser Liste wird ein Plan mit Staging-Test, Rollback-Pfad und Wartungsfenster – und aus dem Plan eine Routine.

Wir übernehmen solche Upgrades als klar umrissenes Projekt oder als Teil des laufenden Betriebs, eingebettet in unsere Individualsoftware-Entwicklung. Wenn du wissen willst, wie weit dein Setup vom Quartalstakt entfernt ist: Buch dir ein kostenloses Erstgespräch – in 30 Minuten klären wir Versionsstand, Risiken und den sinnvollen nächsten Sprung.