Keycloak-Customizing leicht gemacht: Ihr eigenes Theme

05.08.2025 09:06

von Andreas Scheidmeir

Im letzten Blogpost zu Keycloak haben wir gezeigt, wie sich die Open-Source-Lösung zur Identitäts- und Zugriffsverwaltung an eine bestehende Nutzerdatenbank anschließen lässt. Unabhängig davon, ob Sie diesen Weg gehen oder die Benutzerverwaltung direkt in Keycloak nutzen: Der nächste Schritt besteht darin, Clients anzubinden, die ihre Nutzer gegenüber der Keycloak-Instanz authentifizieren.

Während dieses Prozesses verlassen die Nutzer kurzzeitig den Kontext der jeweiligen Client-Applikation und sehen die Standard-Login-Maske von Keycloak:

Keycloak-Seiten im Corporate Design: Wann lohnt sich das Customizing?

Warum sollte man sich die Mühe machen, das Keycloak-Theme individuell anzupassen und dafür in Kauf nehmen, es künftig auch warten zu müssen?

Ein zentraler Grund ist die Corporate Identity (CI): Mit einem eigenen Theme lassen sich sämtliche Aspekte von Keycloak optisch an das Design der eigenen Marke anpassen, inklusive Farben, Logos und Schriftarten. Das sorgt für ein einheitliches Erscheinungsbild und erhöht die Wiedererkennbarkeit sowie den professionellen Eindruck der Anwendung. Nutzer erkennen sofort, dass sie sich auf einer Seite der Organisation befinden. Dies schafft Vertrauen und verringert Unsicherheit beim Login.

Auch die Nutzererfahrung (UX) kann durch ein angepasstes Theme verbessert werden. Seiten lassen sich vertraut strukturieren, überflüssige Felder oder Funktionen entfernen und der Anmeldeprozess insgesamt verständlicher gestalten. Die Sprach- und Textgestaltung kann angepasst werden, in dem z.B. fehlende Lokalisierungen ergänzt und eine zielgruppengerechte Wortwahl für ein besseres Verständnis sorgen, insbesondere bei Fehlermeldungen oder sicherheitsrelevanten Hinweisen.

Trotz dieser Vorteile kann es in bestimmten Fällen sinnvoll sein, das Default-Theme von Keycloak beizubehalten. Dies spart nicht nur Zeit und Entwicklungskosten, sondern reduziert auch den Wartungsaufwand – insbesondere bei künftigen Updates, bei denen individuell angepasste Themes geprüft und ggf. angepasst werden müssen. Gerade bei internen Anwendungen oder technisch orientierten Nutzergruppen ist ein aufwändiges Customizing nicht immer notwendig. In solchen Fällen steht die Funktionalität im Vordergrund – ein schlichtes, funktionierendes Standard-Layout ist dann oft vollkommen ausreichend.

Am Ende bleibt die Entscheidung stets eine Abwägung je Projekt und Zielgruppe: Ein individuell gestaltetes Theme kann die Nutzerbindung stärken und das Vertrauen erhöhen – muss aber technisch und organisatorisch mitgetragen werden.

Welche Möglichkeiten bietet Keycloak, um die Themes anzupassen?

Keycloak stellt ein flexibles System zur Verfügung, das sich in mehrere Theme-Typen unterteilt. Jeder Typ bedient einen bestimmten Bereich der Benutzeroberfläche und kann unabhängig angepasst oder überschrieben werden:

Account – Benutzerkonto-Konsole (Profil, Passwort ändern, Sitzungen verwalten)
Admin – Administrationskonsole für Realm- und Benutzerverwaltung
Email – E-Mail-Vorlagen (z.  Verifizierung, Passwort-Reset)
Login – Login-Formulare, Registrierung, Passwort zurücksetzen usw.
Welcome – Willkommensseite von Keycloak (Startseite ohne Anmeldung)

Ein Theme besteht dabei aus mehreren Bestandteilen:

HTML-Vorlagen (Freemarker Templates .ftl)
CSS-Stylesheets
JavaScript-Dateien
Bilder und Icons
Message-Bundles (z.  für Lokalisierung)
properties (Meta-Informationen)

Dabei ist es nicht notwendig, jeden Theme-Typ vollständig anzupassen. Keycloak erlaubt ein modulares Vorgehen: Sie können gezielt nur die Komponenten verändern, die Sie brauchen – etwa nur das Login-Formular oder einzelne Texte.

Dank des Vererbungssystems können eigene Themes auf bestehenden Themes (z. B. base oder keycloak) aufbauen. Dadurch reicht es oft aus, nur eine kleine Auswahl an Dateien zu überschreiben. Möchte man zum Beispiel nur das Logo und die Farben im Login ändern, so kann man auf dem Standard-Theme aufbauen und lediglich das entsprechende Stylesheet austauschen.

Auch ist es möglich, mehrere Varianten eines Themes anzulegen, um beispielsweise verschiedene Corporate-Designs für unterschiedliche Clients oder Mandanten zu bedienen. So kann je nach Anwendung oder Kundenmarke ein passendes Branding zur Verfügung gestellt werden, bei gleichbleibender technischer Basis.

Technische Umsetzung eines Custom Login Theme

Erinnern wir uns an das eingangs erwähnte Szenario: Die Nutzerverwaltung erfolgt nicht direkt über Keycloak, sondern über ein externes System. In diesem Fall genügt es, für die Benutzer lediglich das Login-Theme anzupassen, um ein konsistentes Nutzererlebnis im eigenen Corporate Design zu bieten.

In unserem Beispiel nutzen wir dazu die Theme-Vererbung und bauen auf dem bestehenden keycloak.v2-Template auf. Statt das komplette Layout neu zu erstellen, tauschen wir gezielt Grafiken, passen Farben an und nehmen minimale Layout-Anpassungen per CSS vor. Dieser Ansatz ist bewusst wartungsarm gewählt: Da die zugrunde liegenden HTML-Templates von Keycloak weiterverwendet werden, müssen bei einem Update lediglich die CSS-Selektoren überprüft werden. Bleiben diese unverändert, ist keine weitere Anpassung nötig.

Falls Sie die technischen Details überspringen möchten, können Sie hier direkt zum Fazit gelangen.

Erstellung des eigenen Themes

Zunächst erwartet Keycloak die Dateien in einer spezifischen Struktur, die wir anlegen müssen:

theme/
	themename/ (in unserem Fall: exensiotheme)
		login/
			theme.properties
			resources/
				css/
				img/
				...

Den Ausgang für unser eigenes Theme bildet die theme.properties Datei:

parent=keycloak.v2
import=common/keycloak

styles=css/login.css

Hier definieren wir über das Parent, von welchem Theme geerbt werden soll und welche Dateien importiert werden. Die common/keycloak Imports stellen sicher, dass das vererbte Theme alle nötigen Dateien erhält und in der noch zu erstellenden login.css definieren wir unsere Anpassungen.

Als nächstes können wir in der login.css die Stile und Grafiken gezielt überschreiben. Um zu wissen, welche Klassen und Selektoren relevant sind, lohnt sich ein Blick in das offizielle Git-Repo oder man inspiziert im Browser den default Login.

:root {
    --keycloak-logo-url: url('../img/exensio_logo_subline.svg');
    --keycloak-bg-logo-url: url("../img/keycloak-bg-exensiored.svg");
    --exensio-red-color: #75042f;
}

#keycloak-bg {
    background-image: var(--keycloak-bg-logo-url);
    background-size: cover;
    background-position: center;
}

div.kc-logo-text {
    background-image: var(--keycloak-logo-url);
    height: 63px;
    width: auto;
    background-repeat: no-repeat;
    background-size: contain;
    margin: 0;
    color: transparent;
}

/* top border */
main > div:first-child {
    border-top: 4px solid var(--exensio-red-color);
}

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

#kc-login:hover {
    background-color: rgba(var(--exensio-red-color), 1.5);
}


.pf-v5-c-form-control:after {
    border-block-end: 1px solid var(--exensio-red-color);
}

Zunächst werden eigene CSS-Variablen definiert, unter anderem für das Firmenlogo, ein individuelles Hintergrundbild sowie die zentrale Markenfarbe. Die Bilder müssen entsprechend im img-Ordner vorhanden sein.

Diese Werte werden anschließend gezielt eingesetzt, um das Erscheinungsbild zu verändern: Das Standard-Logo wird durch das exensio-Logo ersetzt, ein benutzerdefiniertes Hintergrundbild eingebunden und die primäre Akzentfarbe auf verschiedene UI-Elemente wie die obere Rahmenlinie, den Login-Button und die Formularmarkierungen angewendet.

Ein Hinweis: Die kc- bzw. keycloak Selektoren sind universell und sollten sich zwischen Versionen nicht verändern, .pf-Klassen hingegen stammen aus dem Design-Framework PatternFly, das Keycloak verwendet, und müssen bei einem Versionsupdate besonders geprüft werden.

Einbindung in Keycloak

Damit haben wir es schon fast geschafft, wir müssen das eigene Theme nun nur noch in unserer Keycloak-Instanz unterbringen. Dafür erweitern wir das im letzten Blogpost erstellte Keycloak Dockerfile wie folgt:

FROM quay.io/keycloak/keycloak:26.0.7


# NEU: Theme hinzufügen
COPY theme /opt/keycloak/themes


COPY build/libs/keycloak-user-storage-1.0-SNAPSHOT.jar /opt/keycloak/providers/
RUN /opt/keycloak/bin/kc.sh build
# Setze den Entwicklungsmodus als Standard, NICHT für Prod nutzen!
ENTRYPOINT ["/opt/keycloak/bin/kc.sh", "start-dev"]

Zusätzlich zum eigenen Provider legen wir nun auch das eigene Theme unter /opt/keycloak/themes ab und bauen das Image neu.

Wenn wir den Container nun starten und uns im Backend als Administrator einloggen, können wir unter dem Menüpunkt Realm settings/Themes unser eigenes Login-Theme auswählen und aktivieren. Dies setzt das Theme global für alle Clients des Realms, unter Clients können diese auch spezifisch überschrieben werden. Nach einem Logout präsentiert sich Keycloak nun in unseren Farben:

Keycloak Theme-Customizing: So flexibel wie Ihre Anforderungen

Das gezeigte Beispiel ist bewusst einfach gehalten, zeigt aber, wie schnell und unkompliziert sich das Erscheinungsbild des Login-Prozesses an die eigene Corporate- oder Markenidentität anpassen lässt. Dabei ist man keineswegs auf ein einziges Custom-Theme beschränkt: Für unterschiedliche Clients oder Markenwelten können bei Bedarf auch mehrere separate Themes gepflegt werden - vorausgesetzt, der Aufwand lohnt sich im jeweiligen Kontext.

Keycloak bietet dafür eine große Bandbreite an Möglichkeiten: Von oberflächlichen CSS-Anpassungen, die mit minimalem Wartungsaufwand verbunden sind, bis hin zur Umsetzung einer komplett individuellen Nutzererfahrung durch eigene HTML- und Freemarker-Templates. So lässt sich der Grad der Anpassung exakt an die technischen Anforderungen und verfügbaren Ressourcen anpassen.

Wir helfen Ihnen gerne bei der Entwicklung und Absicherung Ihrer modernen Kundenservice-Portale. Lesen Sie hier, bei welchen Themen wir Sie auf dem Weg zu einem zukunftsweisenden Kundenservice begleiten können.

Weitere Blogposts zum Thema Keycloak:

Zurück