Keycloak mit Custom Theming

Wer seine Anwendungen sicher und flexibel in Bezug auf Authentifizierung und Autorisierung gestalten möchte, findet im Open Source Identity Provider Keycloak häufig die passende Softwarelösung.

Beim Login über Keycloak werden Nutzer auf dessen Anmeldeseite weitergeleitet. Wer jedoch bereits mit Keycloak gearbeitet hat, weiß, dass das standardmäßige Styling der Login-Maske oft nicht zur visuellen Identität der eigenen Anwendung oder Website passt.

In den folgenden Abschnitten werfen wir einen genaueren Blick auf die verschiedenen Ansätze, mit denen sich das Erscheinungsbild der Keycloak-Seiten anpassen lässt. Dabei unterscheiden sich die Möglichkeiten nicht nur im Funktionsumfang, sondern auch im Grad der Flexibilität und im benötigten Implementierungsaufwand.

Der Artikel gliedert sich in drei Teile:

Zunächst betrachten wir das Standard-Templating mit CSS, das grundlegende Anpassungen direkt innerhalb von Keycloak ermöglicht.
Anschließend gehen wir auf Quick Themes ein, die einen schnellen und pragmatischen Weg bieten, das Styling zu verändern.
Abschließend stellen wir Keycloakify vor, einen modernen Ansatz, mit dem sich Keycloak-Seiten vollständig komponentenbasiert mit React umsetzen lassen.

Anlegen eines eigenen Keycloak Themes

Ein Keycloak-Theme besteht aus mehreren Bausteinen, darunter HTML-Templates (FreeMarker), Stylesheets, Skripte, Bilder und Message Bundles. In der Praxis wird ein neues Theme fast immer auf Basis eines bestehenden Themes erstellt, das anschließend gezielt erweitert oder überschrieben wird.

Themes liegen im Verzeichnis themes/ der Keycloak Installation. Der Name des Ordners entspricht dem Namen des Themes:

themes/
└── mytheme/
    └── login/
        └── theme.properties

Jeder Theme-Typ (z. B. login, account, email) erhält ein eigenes Unterverzeichnis.

Die zentrale Konfigurationsdatei ist theme.properties. Um ein bestehendes Theme zu erweitern, wird ein Parent definiert:

parent=base
import=common/keycloak

Damit erbt das Theme alle Ressourcen des Standard Themes und erlaubt es, einzelne Bestandteile zu überschreiben.

Während der Entwicklung sollte das Theme Caching deaktiviert werden, um Änderungen ohne Neustart zu sehen:

bin/kc.sh start \
  --spi-theme-static-max-age=-1 \
  --spi-theme-cache-themes=false \
  --spi-theme-cache-templates=false

Oder für Docker:

docker run --rm \
  -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:latest \
  start \
  --spi-theme-static-max-age=-1 \
  --spi-theme-cache-themes=false \
  --spi-theme-cache-templates=false

Eigene CSS-Dateien werden unter resources/css abgelegt und in theme.properties registriert:

styles=css/login.css css/styles.css

Dabei überschreibt die zuletzt geladene Datei Styles des Parent Themes.

Nach dem Anlegen kann das Theme im Admin Console aktiviert werden:

Realm auswählen
Realm Settings → Themes
Login Theme auf mytheme setzen und speichern

Ab diesem Zeitpunkt wird das neue Styling auf der Login Seite verwendet.

ACHTUNG: In produktiven Umgebungen sollte das Caching unbedingt wieder aktiviert werden, da es einen erheblichen Einfluss auf die Performance hat.

Eine detailiertere Beschreibung ist ebenfalls auf der Keycloak Seite zu finden: Keycloak Theming

Das Base Styling ist im GitHub zu finden um die Keys der HTML Elemente auszulesen: Keycloak Base Theme

Theme erstellung mit Quick Theme

Mit der neuen Quick Theme-Funktion bietet Keycloak eine praktische Möglichkeit, Login-Seiten sowie die Account- und Admin-Konsole schnell an das eigene Corporate Design anzupassen. Statt komplexe Themes manuell zu entwickeln, erlaubt das Tool das direkte Konfigurieren von Logos und Farbpaletten über eine grafische Oberfläche. Dabei baut das generierte Theme automatisch auf dem Standard-Keycloak-Theme auf, sodass Administratoren sofort mit bestehenden Layouts arbeiten können. Da sich Quick Theme aktuell noch in der Preview-Phase befindet, muss die Funktion beim Start des Keycloak-Servers explizit aktiviert werden.

bin/kc.[sh|bat] start --features=quick-theme

Oder mit Docker:

docker run -p 8080:8080 \
           -e KEYCLOAK_ADMIN=admin \
           -e KEYCLOAK_ADMIN_PASSWORD=admin \
           quay.io/keycloak/keycloak:latest \
           start --features=quick-theme

Nach der Aktivierung steht im Admin-Interface unter Realm Settings → Themes die beiden neuen Tabs zur Farbpaletten änderung zur Verfügung.

Änderungen an Farben oder Logos werden direkt in einer Vorschau dargestellt. Die Farboptionen basieren auf PatternFly-Variablen, die Keycloak intern für das UI-Styling nutzt. Moderne Browser wie Chrome unterstützen zusätzlich einen Farbwähler mit „Pipetten“-Werkzeug, mit dem Farben beispielsweise direkt aus einem Firmenlogo übernommen werden können. Nach Abschluss der Anpassungen kann das fertige Theme als JAR-Archiv exportiert werden. Dieses Archiv wird anschließend im providers/-Verzeichnis der Keycloak-Installation abgelegt oder alternativ in das themes/-Verzeichnis entpackt, um weitere manuelle Anpassungen vorzunehmen.

ACHTUNG: Aus Sicherheitsgründen sollte ein Theme ausschließlich aus vertrauenswürdigen Quellen installiert werden, da eingebettete Ressourcen wie Bilder potenzielle Angriffsvektoren darstellen können.

Sobald das Theme bereitgestellt wurde, lässt es sich über die Realm-Einstellungen aktivieren und anschließend vollständig im Login-Flow sowie in den Verwaltungsoberflächen testen.

Theme erstellung mit Keycloakify und React

Keycloakify ist ein leistungsstarkes Tool zur Erstellung individueller Keycloak Themes und richtet sich an Entwicklerteams, die mehr Kontrolle über Design und Benutzererlebnis benötigen. Es ermöglicht die Anpassung aller relevanten Oberflächen, von Login- und Registrierungsseiten über die Account Verwaltung bis hin zu E-Mail-Templates und der Admin Console. Im Gegensatz zum klassischen Keycloak-Theming setzt Keycloakify auf moderne Frontend Technologien wie React, Angular oder Svelte.

Im folgenden Beispiel wird ein Keycloak Theme mit React und der Komponenten Library Shadcn erstellt, welches von einem Template abgeleitet wurde.

Erstellen eines Vite Projekts:

npm create vite@latest

Wähle den Namen des Themes, React und Typescript.

Im Verzeichnis des Projekts installieren wir das Shadcn Template und Keycloakify:

npm install keycloakify @oussemasahbeni/keycloakify-login-shadcn

Initialisieren von Keycloakify:

npx keycloakify init

Wähle dann die Seiten aus, welche angepasst werden sollen. In diesem fall nur Login.

Updaten der Vite Konfiguration:

import react from "@vitejs/plugin-react";
import { keycloakify } from "keycloakify/vite-plugin";
import { defineConfig } from "vite";
import path from "node:path";
import tailwindcss from "@tailwindcss/vite"; //new

// https://vite.dev/config/
export default defineConfig({
    plugins: [
        react(),
        tailwindcss(), //new
        keycloakify({
            accountThemeImplementation: "none"
        })
    ],
    resolve: {
        alias: {
            "@": path.resolve(__dirname, "src") //new
        }
    }
});

Updaten des Typescript Paths, in tsconfig.json:

{
    // ...
    "compilerOptions": {
        // ...
        "paths": {
            "@/*": ["./src/*"]
        }
    }
}

In tsconfig.app.json:

{
    "compilerOptions": {
        // ...
        "paths": {
            "@/*": ["./src/*"] //new
        }
    },
    "include": ["src"]
}

Git muss initialisiert werden:

git init .
git add -A
git commit -m "Initial commit"

Nun kann mit dem Befehl npm run storybook eine Preview der Seiten angezeigt werden, um die Komponenten anzupassen.

Um das Colorscheme zu ändern kann man nun in src/login/index.css die Shadcn Variablen ändern. Oder man tauscht die Variablen durch ein generiertes Theme von Tweakcn aus.

Um das generelle Layout anzupassen kann die Datei in src/login/components/Template/Template.tsx angepasst werden. Oder die einzelnen Komponenten selbst.

Mit npm run build-keycloak-theme lässt sich das fertige Theme dann als .jar exportieren und in Keycloak über das Admin interface hinzufügen.

Das Ergebniss könnte wie folgt aussehen:

Fazit

Keycloak bietet heute eine breite Palette an Möglichkeiten, um das Erscheinungsbild seiner Benutzeroberflächen an individuelle Anforderungen anzupassen. Welcher Ansatz dabei der richtige ist, hängt maßgeblich vom gewünschten Grad der Individualisierung, den technischen Rahmenbedingungen sowie dem verfügbaren Entwicklungsaufwand ab.

Quick Theme eignet sich hervorragend für schnelle und unkomplizierte Branding-Anpassungen, etwa das Ändern von Farben oder Logos. Für weitergehende Eingriffe in Struktur, Layout oder Benutzerführung ist dieser Ansatz jedoch nur eingeschränkt geeignet, da tiefere UI- oder UX-Anpassungen aktuell nicht vorgesehen sind.

Für komplexere Anforderungen sind sowohl das klassische native Theming mit CSS und FreeMarker als auch das Theming mit Keycloakify die bessere Wahl. Welche Variante bevorzugt wird, hängt vor allem von den Fähigkeiten und Präferenzen des Entwicklerteams ab. Wer bereits mit modernen Frontend-Frameworks wie React, Angular oder Svelte arbeitet und Wert auf komponentenbasierte Architekturen legt, ist mit Keycloakify bestens beraten. Alternativ lässt sich auch auf Basis des Keycloak Base Themes ein solides und wartungsarmes Styling realisieren, indem gezielt CSS-Overrides eingesetzt werden.

Feedback oder Fragen zu einem Artikel - per E-Mail an [email protected] oder über das Kontaktformular. Wir freuen uns auf eine Kontaktaufnahme!

Beitrag drucken

Kontakt

Neuigkeiten von trion.
Immer gut informiert.