Keycloak Customizing leicht gemacht Teil 2: Keycloakify

10.02.2026 09:06

von Andreas Scheidmeir

Im letzten Teil dieser Blogreihe zum Keycloak-Customizing habe ich gezeigt, wie sich Keycloak mit Bordmitteln an das eigene Corporate Design anpassen lässt. Durch den Einsatz von Themes in Kombination mit CSS und optionalen Freemarker-Templates können Login- und Account-Seiten individuell gestaltet werden. Für viele einfache Anwendungsfälle ist dieser Ansatz vollkommen ausreichend und lässt sich ohne zusätzliche Werkzeuge schnell umsetzen.

In der Praxis zeigt sich jedoch, dass dieser manuelle Ansatz mit zunehmenden Anforderungen an seine Grenzen stößt. Die Pflege mehrerer Themes wird schnell aufwendig, die Wiederverwendbarkeit ist nur eingeschränkt möglich und Änderungen lassen sich nur schwer isoliert testen. Spätestens wenn mehrere Clients, unterschiedliche Designvarianten oder eine enge Einbindung in bestehende Entwicklungs- und Build-Prozesse erforderlich sind, steigt der Wartungsaufwand deutlich.

An dieser Stelle kommt Keycloakify ins Spiel. Was Keycloakify ist und wie es den Prozess des Keycloak-Customizings nachhaltig vereinfachen und beschleunigen kann, möchte ich in diesem Blogpost zeigen.

Was ist Keycloakify?

Während klassische Keycloak-Themes aus statischen HTML- oder Freemarker-Templates in Kombination mit ergänzendem CSS bestehen, verfolgt Keycloakify einen deutlich moderneren Ansatz zur Theme-Entwicklung. Anstatt die HTML-Struktur direkt in Keycloak zu bearbeiten, werden Themes als React-Komponenten in TypeScript entwickelt, lokal gebaut und anschließend als Theme-JAR in Keycloak bereitgestellt.

Der wesentliche Unterschied zum herkömmlichen Workflow liegt in der Entwicklungsumgebung und der verfügbaren Tool-Unterstützung. Mit Keycloakify erfolgt die Entwicklung nicht mehr „direkt im Keycloak-Container“, sondern innerhalb einer etablierten Frontend-Toolchain. Das bringt mehrere Vorteile mit sich:

Komponentenbasierte Entwicklung: UI-Elemente wie Login-Formulare oder Fehlermeldungen werden als wiederverwendbare Komponenten umgesetzt und können konsistent eingesetzt werden.
TypeScript-Unterstützung: Die Typisierung hilft dabei, Fehler frühzeitig im Entwicklungsprozess zu erkennen, ganz ohne ein laufendes Keycloak-Deployment.
Moderne Build-Tools: Themes werden mit gängigen Build-Tools erstellt und als JAR-Artefakt ausgeliefert, anstatt Dateien manuell zusammenzutragen.

Darüber hinaus integriert Keycloakify Storybook als Werkzeug zum isolierten Entwickeln, Visualisieren und Testen von UI-Komponenten. Das vereinfacht nicht nur die Entwicklung, sondern ermöglicht es allen Beteiligten, Screens frühzeitig zu begutachten, bevor sie in Keycloak zum Einsatz kommen. In der Praxis verbessert dieser Ansatz die Testbarkeit und verkürzt Feedback-Schleifen deutlich.

Keycloakify als Alternative zum manuellen Customizing

Wie im letzten Teil dieser Blogreihe zum Keycloak-Customizing gezeigt, lassen sich mit klassischen Keycloak-Themes bereits zahlreiche Anpassungen umsetzen. Mit zunehmenden Anforderungen zeigt sich jedoch, dass dieser Ansatz nur begrenzt skaliert. Keycloakify setzt genau an diesen Schwachstellen an und bringt dafür einen deutlich moderneren Entwicklungsansatz mit.

Wartbarkeit und Wiederverwendbarkeit

Beim manuellen Customizing sind HTML-Strukturen, Styles und Logik häufig eng miteinander verknüpft. Änderungen an einem Theme lassen sich dadurch nur schwer wiederverwenden, insbesondere dann, wenn mehrere Varianten oder unterschiedliche Clients im Einsatz sind.

Keycloakify verfolgt hier einen anderen Ansatz und setzt auf eine komponentenbasierte Top-down-Entwicklung. Wiederkehrende UI-Elemente werden zentral definiert und können konsistent über verschiedene Screens und Themes hinweg eingesetzt werden. Anstatt von Beginn an ein vollständig eigenes Design zu entwickeln, steht das bewährte Keycloak Standard-Design zunächst zur Verfügung und wird gezielt dort erweitert, wo fachliche oder gestalterische Anforderungen dies erfordern.
Das senkt den Initialaufwand, reduziert die Projektkomplexität und minimiert Risiken. Gleichzeitig bleibt die notwendige Flexibilität erhalten, einzelne Seiten oder Komponenten direkt oder zu einem späteren Zeitpunkt gezielt anzupassen.

Schnelle Testbarkeit durch integriertes Storybook

Ein zentraler Vorteil von Keycloakify ist die Möglichkeit, Themes ohne laufenden Keycloak-Server zu entwickeln und zu testen. Über das integrierte Storybook lassen sich einzelne Screens wie etwa Login, bis hin zu einzelnen Fehlerzuständen isoliert darstellen und überprüfen.

Dadurch verkürzt sich der Feedback-Zyklus erheblich: Layout-Änderungen, Farbvarianten oder neue Komponenten können sofort bewertet werden, ohne dass Keycloak neu gestartet oder ein Container gebaut werden muss. Gerade in der Zusammenarbeit mit Design- und UX-Teams oder Product Ownern ist dies ein deutlicher Gewinn.

Deployment als JAR

Auch beim Deployment unterscheidet sich Keycloakify deutlich vom manuellen Ansatz. Das fertige Theme wird als JAR-Datei gebaut und kann nahtlos in bestehende Build- und Deployment-Pipelines integriert werden. In containerisierten Umgebungen, etwa bei der Nutzung von Docker oder Kubernetes, vereinfacht dies die Auslieferung und Versionierung erheblich. Themes werden damit wie reguläre Artefakte behandelt und nicht mehr als lose Sammlung von Dateien im Container gepflegt.

Praxisbeispiel: Theme Varianten

Ausgangsszenario

In vielen Projekten wird Keycloak nicht nur für eine einzelne Anwendung oder Marke eingesetzt, sondern fungiert als zentraler Identity Provider für mehrere Clients. Optisch unterscheiden sich diese Clients oft nur in Details, etwa durch ein abweichendes Farbschema, ein eigenes Logo oder ein individuelles Hintergrundbild. Die grundlegende Struktur der Login- und Registrierungsseiten bleibt dabei meist identisch.

Beim manuellen Customizing, wie im letzten Teil dieser Blogreihe beschrieben, führt dieses Szenario schnell zu mehreren nahezu identischen Themes. Jede Änderung an Layout oder Struktur muss in allen Varianten nachvollzogen werden. Der Pflegeaufwand steigt, Redundanzen sind kaum zu vermeiden und das Risiko inkonsistenter Anpassungen nimmt deutlich zu.

In diesem kurzen Beispiel zeige ich, wie sich dieses Problem mit Keycloakify elegant lösen lässt.
Falls Sie die technischen Details überspringen möchten, können Sie hier direkt zum Fazit gelangen.

Anwendung am Beispiel

Hinweis: Auf die grundlegende Einrichtung von Keycloakify gehe ich an dieser Stelle nicht näher ein. Diese wird im offiziellen Quick Start ausführlich beschrieben.

Im Demoprojekt wird das Konzept anhand mehrerer Theme-Varianten umgesetzt, die sich ausschließlich im Branding unterscheiden. Die zugrunde liegende Struktur der Login-Seiten, die verwendeten Komponenten sowie das Layout sind für alle Varianten identisch.

Damit Keycloakify und später auch Keycloak selbst die einzelnen Varianten unter unterschiedlichen Namen ansprechen kann, müssen diese zunächst in der vite.config.ts definiert werden:

export default defineConfig({
    plugins: [
        react(),
        keycloakify({
            …
            themeName: [
                "exensio-keycloakify",
                "exensio-blue",
                "exensio-green"
            ],
            …
        })
    ]
});

Anschließend definieren wir die Basis-Styles in einer gemeinsamen CSS-Datei. Dazu gehören in diesem Beispiel unter anderem eine eigene Schriftart sowie allgemeine Regeln zur Farbgestaltung. Farb- und markenspezifische Unterschiede werden über CSS-Variablen abgebildet, die in den jeweiligen Theme-Varianten überschrieben werden.

Jede Theme-Variante definiert dabei lediglich:

eine eigene Akzentfarbe
ein individuelles Hintergrundbild

main.css

@import url('https://fonts.googleapis.com/css2?family=Source+Sans+3:ital,wght@0,200..900;1,200..900&display=swap');

body {
    font-family: "Source Sans 3", sans-serif;
}

/* top border */
.kcFormCardClass {
    border-color: var(--accent-color);
}

/* Login button */
#kc-login {
    background-color: var(--accent-color);
}

#kc-login:hover {
    background-color: oklch(from var(--accent-color) calc(l - .1) c h);
}

Varianten-Beispiel: red.css

@import url(./main.css);

:root {
    --accent-color: oklch(0.3625 0.1418 8.21);
}

body.kcBodyClass {
    background: url(../assets/keycloak-bg-exensiored.svg) no-repeat fixed;
    background-size: cover;
}

Welche Variante zur Laufzeit verwendet wird, ergibt sich aus dem in Keycloak konfigurierten Theme-Namen. Dieser Wert steht der Anwendung im kcContext zur Verfügung und kann genutzt werden, um die passende Stylesheet-Variante zu laden. Im React-Code lässt sich dies beispielsweise wie folgt umsetzen:

function useThemeBasedCss(kcContext: KcContext) {
    useMemo(() => {
        switch (kcContext.themeName) {
            case "exensio-keycloakify":
                import("./styles/red.css");
                break;
            case "exensio-blue":
                import("./styles/blue.css");
                break;
            case "exensio-green":
                import("./styles/green.css");
                break;
        }
    }, []);
}

Diese Anpassung wirkt sich auf alle von Keycloakify unterstützten Seiten aus, da sie im Rahmen der Top-down-Entwicklung auf die DefaultPage angewendet wird, welche sämtliche Seitenvarianten kapselt.

Am Layout der einzelnen Seiten nehmen wir in diesem Beispiel keine Änderungen vor, sodass weiterhin das Keycloak-Default-Layout verwendet wird. Sollte dennoch eine individuelle Anpassung einzelner Seiten erforderlich sein, ist dies jederzeit möglich: Mit dem Befehl npx keycloakify eject-page wird eine Kopie der gewünschten Seite im Projekt erzeugt, die anschließend frei angepasst werden kann.

Varianten schnell testen mit Storybook

Dank der integrierten Storybook-Unterstützung lassen sich die zuvor definierten Theme-Varianten direkt testen, ohne dass sie zunächst in einem Keycloak-Container deployt werden müssen. Änderungen am Styling oder Branding werden sofort sichtbar, wodurch sich Entwicklungs- und Feedback-Zyklen deutlich verkürzen.

Im Demoprojekt werden die Theme-Varianten über einen gemockten kcContext bereitgestellt. So kann für jede Story gezielt festgelegt werden, welcher Theme-Name verwendet wird. Storybook rendert die Login-Seiten anschließend exakt so, wie sie später in Keycloak erscheinen – inklusive der jeweils aktiven Farb- und Branding-Variante.

Die benötigten Stories für die zu testenden Seiten werden mit dem Befehl npx keycloakify add-story erzeugt. Standardmäßig verwendet die generierte Story die erste konfigurierte Theme-Variante (in diesem Beispiel die rote Variante). Um weitere Varianten darzustellen, wird der kcContext in der jeweiligen *.stories.tsx angepasst:

export const Default: Story = {
    render: () => <KcPageStory />
};

export const VariantBlue: Story = {
    render: () => (
        <KcPageStory
            kcContext={{
                themeName: "exensio-blue"
            }}
        />
    )
};

export const VariantGreen: Story = {
    render: () => (
        <KcPageStory
            kcContext={{
                themeName: "exensio-green"
            }}
        />
    )
};

Keycloakify Theme Variante: exensio-blau

Keycloakify Theme Variante: exensio-gruen

Skalierbares Customizing mit Keycloakify

Keycloak bietet bereits mit seinen Bordmitteln solide Möglichkeiten zur Anpassung der Benutzeroberfläche. Wie im letzten Teil dieser Blogreihe zu Keycloak-Customizing gezeigt, lassen sich mit klassischen Themes auf Basis von Freemarker und CSS viele Anforderungen umsetzen. Für einfache Szenarien oder punktuelle Anpassungen ist dieser Ansatz nach wie vor eine valide Option.

Sobald jedoch mehrere Clients, unterschiedliche Designvarianten oder eine engere Einbindung in bestehende Entwicklungsprozesse erforderlich sind, spielt Keycloakify seine Stärken aus: Die komponentenbasierte Entwicklung, die Möglichkeit zur isolierten UI-Entwicklung mit Storybook sowie die saubere Auslieferung als JAR führen zu deutlich besserer Wartbarkeit, Testbarkeit und Wiederverwendbarkeit.

Keycloakify ersetzt den klassischen Ansatz nicht zwangsläufig, sondern ergänzt ihn sinnvoll. Für Projekte mit steigender Komplexität, mehreren Clients oder höheren Anforderungen an Entwicklungs- und Deployment-Workflows bietet es eine zukunftssichere Alternative, die sich nahtlos in moderne Frontend- und Deployment-Prozesse einfügt.

Wir helfen Ihnen gerne bei der Entwicklung und Absicherung Ihrer modernen Kundenservice-Portale. Lesen Sie hier, wie wir Sie bei der Einführung von Keycloak begleiten können.

Weitere Blogposts zum Thema Keycloak:

Zurück