Cloakey: Ein Keycloak-Login in eigenen Farben, ohne ein Theme zu bauen
Wir setzen Keycloak in vielen Projekten ein. Es ist ein ausgereiftes IAM und für die meisten unserer Kund:innen die richtige Wahl. Eine Herausforderung wiederholt sich aber in praktisch jedem Projekt: Sobald die erste Login-Seite steht, fragt jemand, ob man sie nach Wünschen stylen und anpassen kann.
Darauf hatten wir bisher nur die Antwort, dass es ginge, aber einige Tage Arbeit bräuchte. Entweder überschreibt man die FreeMarker-Templates von Keycloak, oder man setzt pro Kund:in ein Keycloakify-Projekt auf und trägt es durch jedes Keycloak-Upgrade. Beides funktioniert. Beides ist für den Wunsch «unsere Farbe, unser Logo, bitte nicht so eckig» verhältnismässig aufwändig und teuer. Ein Sprint für ein Logo, zwei Farben und eine Schrift.
Deshalb haben wir Cloakey gebaut. Damit dauert es nur noch zehn Minuten.
Was Cloakey ist
Cloakey ist ein Konfigurator im Browser für Teams, die Keycloak betreiben. Links stellt man ein, rechts sieht man sofort das Resultat auf einer echten Keycloak-Login-Seite. Wer zufrieden ist, wählt seine Keycloak-Version und lädt ein fertiges Theme-JAR herunter. Ein Account braucht es dafür nicht.
Der kürzeste Weg besteht aus zwei Eingaben: Markenfarbe und Logo. Aus der einen Farbe leitet Cloakey den Rest ab, also Hover-Zustände, Fokusringe, Rahmen und die leicht eingefärbten Grautöne im Hintergrund. Wer mehr will, klappt die weiteren Bereiche auf.
Was sich einstellen lässt
Die Auswahl ist bewusst eingeschränkt. Alles, was sich ändern lässt, haben wir in unseren Projekten schon einmal gebraucht:
- Farben: Primärfarbe, Hintergrund, Text und Flächen. Was nicht gesetzt ist, leitet Cloakey aus der Primärfarbe ab.
- Logo als Upload oder per URL.
- Layout: zentrierte Karte, Split-Screen mit Markenfläche oder ein Formular ohne Karte.
- Hintergrund als Farbe, Verlauf oder Bild.
- Schrift aus einer Liste lizenzsicherer Fonts. Die Schriften liegen im JAR, die Login-Seite lädt nichts von fremden Servern.
- Dark Mode: aus, an oder der Präferenz des User-Clients folgend.
- Eckenradien, Rahmenstärken und Schatten.
- Position der Social-Login-Buttons, Sprachwahl unter der Karte, Realm-Name ein- oder ausblenden.
- Custom CSS für alles, was oben fehlt.
Die vier Logins unten stammen alle aus demselben Theme. Geändert wurden nur Farbe, Layout, Hintergrund und Schrift. Der Link unter jedem Bild öffnet die jeweilige Konfiguration live in Cloakey, wo man sie weiter anpassen kann.
Die Vorschau zeigt nicht nur die Anmeldeseite. Ein Keycloak-Login besteht aus bis zu 38 Seiten: Registrierung, Passwort zurücksetzen, E-Mail bestätigen, OTP einrichten, WebAuthn, Fehlerseiten, Logout-Bestätigung und so weiter. Jede davon lässt sich in der Vorschau aufrufen, auf Wunsch mit Validierungsfehlern und in Tablet- oder Mobile-Breite. Das Theme deckt sie alle ab. Wer schon einmal ein eigenes Theme gebaut hat, weiss, dass die eine oder andere Seite auch mal vergessen geht und erst nach dem Go-live auffällt.
Was man sieht, bekommt man auch
Die Vorschau und das heruntergeladene JAR entstehen aus derselben Konfiguration und demselben Code. Das war uns beim Bauen wichtiger als jede einzelne Einstellung.
Das Theme ist ein Keycloakify-Theme mit Tailwind.
Jeder visuelle Wert darin ist eine CSS-Variable mit dem Präfix --kct-.
Der Konfigurator kompiliert die Einstellungen zu einem kleinen Stylesheet,
das genau diese Variablen überschreibt:
:root {
--kct-color-primary: #059669;
--kct-radius-lg: 16px;
/* ... */
}
Die Vorschau lädt dieses Stylesheet in die echten Theme-Komponenten. Beim Download hängt der Browser dasselbe Stylesheet an ein Basis-JAR, das unsere CI vorgebaut hat. Einen Server, der Themes baut, gibt es nicht.
Weil das Theme für alle dasselbe ist und sich nur die Konfiguration unterscheidet, können wir es zentral testen. Alle 38 Seiten liegen als Storybook-Stories vor. Unsere CI vergleicht jede davon pixelgenau mit einem eingecheckten Referenzbild. Eine Änderung, die eine Seite kaputt macht, bricht den Build, statt in einem JAR zu landen.
Aus dieser Architektur ergeben sich drei Dinge, die wir erst im Nachhinein richtig schätzen gelernt haben. Die Konfiguration ist eine kleine JSON-Datei mit Schema-Version. Sie lässt sich exportieren und neben den Infrastruktur-Code ins Repository legen. Kommt das nächste Keycloak-Major, importiert man sie wieder und lädt das JAR neu herunter. Ausserdem trägt jedes JAR seine eigene Konfiguration mit sich. Wer in einem Jahr die Farbe anpassen will, zieht das JAR in den Konfigurator und macht dort weiter. Die gesamte Konfiguration steckt zudem im Link. Ein Entwurf lässt sich per URL an Kolleg:innen schicken, ohne dass irgendwo etwas gespeichert wird.
Installation
Das JAR kommt ins providers/-Verzeichnis von Keycloak,
und in den Realm-Einstellungen wählt man unter «Themes» das Login-Theme cloakey.
Im Container reicht ein Volume-Mount oder eine Zeile im Containerfile:
FROM quay.io/keycloak/keycloak:26.0
COPY keycloak-theme-kc26.jar /opt/keycloak/providers/
Cloakey zeigt die Anleitung beim Download an und legt sie zusätzlich als README.md ins JAR,
mit den echten Dateinamen statt Platzhaltern.
Cloakey unterstützt Keycloak 22 bis 26. Die Version wählt man vor dem Download. Sie bestimmt nur, welches Basis-JAR verwendet wird. Am Design ändert sie nichts.
Kostenlos, mit einer Bedingung
Generierte Themes darf man kostenlos nutzen, auch kommerziell. Die eine Bedingung: Der Hinweis «Theme generated using Cloakey by nxt» am Seitenende bleibt. Technisch ist das eine Theme-Property im JAR, und wer sie entfernen will, kann das. Wir bitten darum, es nicht zu tun. Wer den Hinweis loswerden möchte, kann uns gerne an hallo@nxt.engineering schreiben.
Warum wir das gebaut haben
Cloakey ist aus unserer IAM-Beratung heraus entstanden. Wir wollten aus der immer gleichen Projektaufgabe ein Werkzeug machen, das ein Team, das Keycloak betreibt, in zehn Minuten bedienen kann, ohne dafür ein Theme-Projekt aufzusetzen.
Keycloakify hat jemand unter dem Beitrag auf Reddit als «das beste Werkzeug für Entwickler:innen, aber nicht für Kund:innen» beschrieben. Das trifft genau unsere Intention. Cloakey trägt die Keycloakify-Abhängigkeit, die Versions-Pins und den Upgrade-Aufwand auf unserer Seite, damit die Anwender:innen nur noch eine Farbe und eine Schrift auswählen müssen.
Weshalb Cloakey statt Agent
«Mit Claude Code dauert eine FTL-Anpassung fünf Minuten.» Ein Team aus der Schweiz betreibt ein stark angepasstes Keycloak mit eigenen Authenticators und Flows. Die FreeMarker-Templates passen sie mit Claude Code und einer Figma-Anbindung an. Mit ein paar eigenen Skills sei das inzwischen eine Sache von Minuten.
Das glaube ich sofort. Nur ändert der Agent nichts daran, wem der Code gehört. Was Claude Code schreibt, ist Template-Code, und für den bleibt das eigene Team verantwortlich: reviewen, im Browser prüfen, beim nächsten Keycloak-Major noch einmal prüfen, weil sich die Basis-Templates darunter bewegen. Dass das bei diesem Team gut läuft, liegt am Gerüst, das es sich gebaut hat: Skills, Review-Routine, vermutlich eine Visual-Regression-Pipeline. Nichts davon gibt es gratis.
Cloakey zieht diese Grenze anders. Der Template-Code liegt bei uns und wird bei uns getestet. Pro Kund:in ändert sich eine einzige JSON-Datei mit Farben, Logo und Schrift. Wer will, lässt seinen Coding-Agenten diese Datei bearbeiten. Der Diff im Review ist dann ein Hex-Wert und ein Schriftname, und der Agent kann die Recovery-Codes-Seite nicht kaputt machen, weil er kein Template anfasst.
Das funktioniert genau so lange, bis jemand eine Seite braucht, die wir nicht abdecken, oder einen Regler, den wir nicht anbieten. Dann ist man wieder in Keycloakify-Land, oder eben bei FTL plus Java. Wie oft das passiert, wissen wir noch nicht.
Wie es weitergeht
Aus der Community kam mehrmals derselbe Wunsch: gestaltete E-Mail-Templates, die zum Login passen. Das rückt auf unserer Liste nach oben. Ob die Account-Konsole ebenfalls ein Theme braucht oder ob das Login reicht, ist für uns noch offen.
Im Konfigurator gibt es einen Feedback-Knopf. Wer eine Login-Seite hat, die sich mit Cloakey nicht abbilden lässt, soll ihn drücken. Für allfällige Fehler im Theme gerne auch. Ich lese jedes Feedback selbst.
