Upgrade auf Keycloak 26 verursacht das Custom Themes nicht mehr funktionieren

Das Upgrade auf Keycloak 26 bringt zahlreiche Neuerungen mit sich, darunter die Unterstützung von Organisationen, eine verbesserte Multi-Site-Deployment-Fähigkeit und ein neues, modernes Login-Theme (v2). Das neue Login-Theme sorgt dafür, dass bestehende Anpassungen nicht mehr wie gewohnt funktionieren – und in vielen Fällen zu Fehlern führen.

Was ist Keycloak eigentlich? Hier habe ich bereits einen Artikel über Keyloack geschrieben: Keycloak - Was ist es und wofür wird es verwendet

Was ist passiert?

Eine der größten Änderungen in Keycloak 26 ist die Einführung des neuen Login-Themes (v2). Dieses neue Theme bietet:

• Modernes, responsives Design
• Unterstützung für Dark Mode
• Automatische Anpassung an Nutzerpräferenzen

Während diese Änderungen für Benutzer der Standard-Login-Templates automatisch und reibungslos greifen, trifft das auf benutzerdefinierte Themes (Custom Themes) leider nicht zu.

Warum funktionieren Custom Themes in Keycloak 26 nicht mehr?

Die Inkompatibilität resultiert aus mehreren Änderungen, die in Keycloak 26 vorgenommen wurden:

1. Neue Dateistrukturen und Pfade
   Viele Drittanbieter-Bibliotheken und Ressourcen haben neue Pfade oder wurden vollständig ersetzt. Custom Themes, die auf alten Bibliothekspfaden basieren, können diese Ressourcen nicht mehr finden und erzeugen dadurch Fehler.
2. Geänderte HTML- und CSS-Struktur
   Das neue v2-Theme bringt eine überarbeitete HTML- und CSS-Struktur mit sich, um modernes Design und Dark Mode zu unterstützen. Individuelle Themes, die auf der alten Struktur basieren, sind dadurch inkompatibel und erfordern umfangreiche Anpassungen.
3. JavaScript-Änderungen
   Keycloak hat die JavaScript-Dateien aktualisiert, um eine bessere Performance und Funktionalität zu gewährleisten. Themes, die auf den alten Skripten aufbauen, können ebenfalls fehlschlagen.
4. Fehlende Fallback-Unterstützung
   Keycloak 26 bietet keine Fallback-Option, um Custom Themes im alten Format weiterhin zu verwenden. Das bedeutet, dass Anpassungen zwingend auf die neue Struktur migriert werden müssen.

Was muss getan werden, um Custom Themes zu migrieren?

Wenn Sie ein Custom Theme verwenden, führt kein Weg an einer Migration vorbei. Folgende Schritte sind notwendig:

1. Überprüfung der neuen Theme-Struktur
   Lesen Sie die Keycloak Theme Customization Guide-Dokumentation für Keycloak 26, um die Änderungen in der Struktur und den Ressourcen zu verstehen.
2. Anpassung der Ressourcenpfade
   Aktualisieren Sie die Verweise auf Drittanbieter-Bibliotheken und CSS-Dateien, um die neuen Pfade zu berücksichtigen.
3. Überarbeitung von HTML und CSS
   Passen Sie Ihre Themes an die neue HTML- und CSS-Struktur des v2-Themes an. Dies erfordert unter Umständen eine vollständige Neugestaltung Ihrer Login- und Registrierungsseiten.
4. Testing und Debugging
   Testen Sie Ihre Anpassungen ausführlich in einer Entwicklungsumgebung, bevor Sie diese in der Produktion einsetzen. Achten Sie dabei insbesondere auf die Kompatibilität von Browsern und die Unterstützung des Dark Modes.

Geht das nicht leichter?

Sollten Sie keine gravierenden Theme-Änderungen benötigen, empfiehlt es sich ein komplett neues Theme zu erstellen und direkt für die gewünschte Keycloak Version zu builden. Schauen Sie mal in meiner Download Sektion nach, dort können Sie auch ein kompatibles Keycloak 26 Themes kaufen.