Keycloak: Erscheinungsbild anpassen

Branding Ihrer Keycloak-Loginseiten, Account-Konsole und E-Mails auf Stackhero leicht gemacht: Legen Sie Ihre Farben, Ihr Logo, Ihre Texte fest und erstellen Sie sogar vollständig eigene Themes mit dem integrierten Online-Editor.

👋 Willkommen in der Stackhero-Dokumentation!

Stackhero bietet einen Keycloak Cloud Service, mit dem Sie in nur 2 Minuten einen produktionsbereiten Identity Provider bereitstellen können:

• Unbegrenzte Anzahl an Benutzern, Realms und Clients
• Unterstützung für OpenID Connect, OAuth 2.0, SAML 2.0, Social Login, LDAP- und Active Directory-Föderation
• Eigene Domain mit integriertem HTTPS für sicheren Zugriff (zum Beispiel https://login.ihre-firma.com)
• Individuelle Themes: Gestalten Sie Ihre Login-Seiten, das Account-Portal und E-Mails ganz einfach mit dem integrierten Online-Editor
• Dedizierter E-Mail-Server mit SPF, DKIM und DMARC, sodass Kontobestätigungen und Passwort-Resets automatisch für Sie abgewickelt werden
• Integrierte PostgreSQL-Datenbank, mit Administrationskonsole auf einem eigenen, abschaltbaren Port
• One-Click-Updates halten Ihr System ohne manuellen Aufwand aktuell

Verbringen Sie Ihre Zeit mit Entwicklung, nicht mit Konfiguration: Testen Sie die Keycloak Cloud-Lösung von Stackhero in weniger als 5 Minuten.

Erscheinungsbild Ihres Keycloak anpassen

Die Login-Seite ist einer der ersten Berührungspunkte für Ihre Nutzer. Mit Stackhero können Sie diese in wenigen Minuten individuell gestalten: Legen Sie Ihre Farben, Ihr Logo und die Texte für jede unterstützte Sprache fest. Das gleiche Prinzip gilt für die von Keycloak versendeten E-Mails.

Es stehen Ihnen zwei Hauptwerkzeuge zur Verfügung, beide sind in Ihrem Service enthalten:

• Der Themes Editor, ein Online-Dateieditor, in dem Ihr Theme verwaltet wird.
• Quick Theme, der visuelle Theme-Designer direkt in Ihrer Keycloak-Administrationskonsole, mit dem Sie Farben und Branding ohne CSS-Kenntnisse auswählen können.

Kein SSH, kein Rebuild, kein Redeploy erforderlich.

Den Themes Editor öffnen

Auf Ihrer Service-Seite im Stackhero Dashboard finden Sie neben Ihrer Administrationskonsole eine Themes editor-URL:

https://your-domain.com:4443/stackhero_themes/

Melden Sie sich mit Ihren Keycloak-Administrator-Zugangsdaten an – dieselben, die Sie auch für die Administrationskonsole verwenden.

Beachten Sie dabei zwei wichtige Punkte:

• Der Editor läuft auf dem Administrationsport, nicht auf dem Port, den Ihre Anwendungen nutzen. Wenn Sie diesen Port in Ihrer Stackhero-Firewall schließen, sind sowohl die Administrationskonsole als auch der Editor nicht mehr erreichbar. Ihre Anwendungen authentifizieren weiterhin wie gewohnt.
• Alle Änderungen, die Sie hier vornehmen, werden auf der Festplatte Ihres Dienstes gespeichert, sind in Ihren Backups enthalten und bleiben auch nach Neustarts und Updates erhalten.

Sie finden dort zwei Verzeichnisse:

Jedes Verzeichnis enthält eine README.md mit aktueller Dokumentation passend zu Ihrer Service-Version.

Ihr Theme ist bereit zur Bearbeitung

Öffnen Sie themes/ und Sie finden ein Verzeichnis default/. Dies ist Ihr aktives Theme, das bereits von Ihrer Keycloak-Instanz verwendet wird. Es muss nichts ausgewählt werden: Bearbeiten Sie einfach die Dateien und sehen Sie die Änderungen sofort.

Vorkenntnisse zu Keycloak-Themes sind nicht erforderlich. Jede Datei enthält bereits gängige Einstellungen, die Sie anpassen können, mit dem aktuellen Keycloak-Wert als auskommentiertes Beispiel. Um einen Wert zu ändern, entfernen Sie das Kommentarzeichen, passen Sie den Wert an und speichern Sie die Datei.

Bleibt eine Zeile auskommentiert, verwendet Keycloak den Standardwert. So bleibt Ihr Service immer kompatibel mit dem Standardverhalten von Keycloak, auch nach Updates.

Ihr Logo aktualisieren

Öffnen Sie default/login/resources/img/. Dort finden Sie die beiden aktuell auf Ihrer Login-Seite verwendeten Bilder. Laden Sie Ihr eigenes Logo unter demselben Dateinamen keycloak-logo-text.svg hoch und aktualisieren Sie die Login-Seite mit Ctrl+F5 (Cmd+Shift+R auf macOS).

Das ist alles, was Sie tun müssen. Es ist kein Bearbeiten weiterer Dateien oder Neustart des Dienstes nötig: Die Änderungen werden sofort nach dem Speichern übernommen. Um das Hintergrundbild zu ändern, ersetzen Sie keycloak-bg-darken.svg im selben Ordner.

Wenn Sie andere Dateinamen verwenden möchten, passen Sie die Referenzen im Abschnitt "Your logo" in default/login/resources/css/stackhero.css an.

Farben festlegen

In stackhero.css finden Sie Variablen, die bereits mit den aktuellen Werten versehen sind:

:root {
  /* ---------- Colors ---------- */
  /* The buttons */
  /* --pf-v5-global--primary-color--100: #06c; */
  /* The buttons, while hovered */
  /* --pf-v5-global--primary-color--200: #004080; */
  /* The links */
  /* --pf-v5-global--link--Color: #06c; */
  /* The colored line on top of the login box */
  /* --keycloak-card-top-color: #06c; */

Um eine Änderung zu übernehmen, entfernen Sie die Kommentarzeichen, setzen Sie Ihre Farbe, speichern Sie und laden Sie die Seite neu. Das war's.

Während der Bearbeitung: Ihr Browser cached Theme-CSS, Bilder und Skripte für eine Stunde. Wenn Sie iterativ arbeiten, laden Sie die Seite immer mit Ctrl+F5 neu, um Ihre letzten Änderungen zu sehen. Ihre Besucher sehen die Aktualisierungen innerhalb einer Stunde.

Sie haben volle Kontrolle: Die Datei ist reines CSS und wird zuletzt geladen, sodass Sie jeden Stil überschreiben können. Nutzen Sie die DevTools Ihres Browsers (F12), um Elemente zu inspizieren. Keycloak 26 verwendet das PatternFly Design System, daher sind die meisten Farbvariablen als --pf-v5-global--* benannt und können in :root überschrieben werden.

Ihren Firmennamen festlegen

Dafür ist keine Theme-Bearbeitung nötig. Öffnen Sie in der Administrationskonsole Realm settings > General und tragen Sie den Display name ein. Dieser Name erscheint auf den Login-Seiten und in E-Mails.

Texte ändern, in mehreren Sprachen

Sie können Texte anpassen, ohne CSS oder HTML zu bearbeiten. In default/login/messages/messages_en.properties finden Sie alle Texte des Login-Formulars mit den Standardformulierungen. Um eine Zeile zu ändern, entfernen Sie das #, schreiben Sie Ihren eigenen Text und speichern Sie:

loginAccountTitle=Sign in to Acme
doLogIn=Sign in
doForgotPassword=I forgot my password

Fügen Sie Dateien wie messages_fr.properties für Französisch oder messages_de.properties für Deutsch hinzu und aktivieren Sie diese Sprachen in der Administrationskonsole unter Realm settings > Localization.

Tipp: Im Tab Localization gibt es auch einen Bereich Realm overrides, mit dem Sie Texte direkt in der Konsole ändern können – ganz ohne Dateibearbeitung oder Neustart. Nutzen Sie die Methode, die am besten zu Ihrem Workflow passt.

E-Mails branden

Keycloak versendet E-Mails zur Adressbestätigung, Passwortzurücksetzung und für Benutzereinladungen. In default/email/messages/messages_en.properties finden Sie die Standard-Betreffzeilen und Nachrichten, die Sie anpassen können:

emailVerificationSubject=Confirm your Acme account
passwordResetSubject=Reset your Acme password

Beim Bearbeiten der E-Mail-Inhalte beachten Sie bitte:

• Belassen Sie die Platzhalter {0}, {1}, {2} (Keycloak ersetzt diese durch Link, Anzeigename und Zeitangabe).
• Apostrophe werden durch doppeltes Schreiben (don''t) escaped.

Um das HTML einer E-Mail zu überschreiben, kopieren Sie die gewünschte Vorlage aus dem Keycloak base email theme nach default/email/html/ und bearbeiten Sie Ihre Kopie.

Stackhero richtet den E-Mail-Versand für Sie ein, inklusive SPF, DKIM und DMARC. Konfigurieren Sie dies unter Realm settings > Email mit Host und Port, die auf Ihrer Service-Seite angegeben sind.

Wenn Sie Ihr Theme zurücksetzen müssen

Falls etwas schiefgeht, können Sie das gesamte default-Verzeichnis löschen und Ihren Service neu starten. Stackhero erstellt dann ein frisches Standard-Theme und stellt das gewohnte Keycloak-Erscheinungsbild wieder her.

Ihre Realms, Benutzer und Clients sind in Ihrer Datenbank gespeichert und bleiben davon unberührt.

Theme visuell gestalten mit Quick Theme

In Ihrer Keycloak-Administrationskonsole finden Sie Quick Theme, den visuellen Theme-Designer von Keycloak. Laden Sie ein Logo hoch, wählen Sie Ihre Farben, sehen Sie eine Vorschau der Login- und Account-Konsolen und laden Sie das fertige Theme als .jar-Datei herunter.

Um es zu installieren, legen Sie die Datei per Editor im Verzeichnis themes/ ab und starten Sie Ihren Service neu. Das .jar wird in ein Theme-Verzeichnis entpackt und das Archiv entfernt:

themes/acme.jar        wird zu     themes/acme/

Das neue Theme erscheint dann unter Realm settings > Themes. Sie können die Dateien anschließend weiterhin manuell bearbeiten, wenn Sie möchten.

Diese Methode unterstützt auch Themes, die mit Keycloakify erstellt wurden, oder von einem Designer bereitgestellt werden. Jede .jar- oder .zip-Datei mit einem Theme kann so installiert werden. Gibt es bereits ein Theme mit demselben Namen, wird das neue als acme-1 installiert – so werden bestehende Themes nie überschrieben. Ist die Datei kein Theme, bleibt sie einfach unangetastet und Keycloak startet wie gewohnt.

Eine Marke pro Realm: White-Label-Unterstützung

Themes werden pro Realm in Realm settings > Themes ausgewählt, mit Optionen für jeden Seitentyp: Login, Account, Admin und E-Mail. Einzelne Anwendungen können in den Client-Einstellungen auch ihr eigenes Login-Theme festlegen.

Wenn Sie mehrere Marken betreiben oder White-Label-Lösungen anbieten, verwenden Sie je Marke einen eigenen Realm und weisen Sie jedem ein individuelles Theme zu:

1. Kopieren Sie im Editor das Verzeichnis default und benennen Sie die Kopie um (z. B. acme).
2. Starten Sie Ihren Service neu.
3. Öffnen Sie in der Administrationskonsole den entsprechenden Realm und wählen Sie acme als Login-Theme aus.

Jeder Realm, den Sie nicht explizit konfigurieren, verwendet weiterhin Ihr default-Theme.

Keycloak Theme-Struktur verstehen

Ein Theme ist ein Verzeichnis mit Unterverzeichnissen für jeden Seitentyp:

themes/
  acme/
    login/                             # Benutzer-Loginseiten
      theme.properties                 # Theme-Vererbung und CSS-Includes
      resources/css/stackhero.css      # Ihr CSS
      resources/img/logo.svg           # Ihre Bilder
      messages/messages_en.properties  # Ihre Texte
    account/                           # Benutzerprofil-Verwaltung
    admin/                             # Erscheinungsbild der Admin-Konsole
    email/                             # E-Mail-Vorlagen

Themes erben von den Standard-Keycloak-Themes und überschreiben nur, was Sie benötigen. Eine typische login/theme.properties sieht so aus:

parent=keycloak.v2
styles=css/styles.css css/stackhero.css

• parent legt das Basistheme fest.
• styles listet die zu ladenden CSS-Dateien auf. Platzieren Sie Ihr CSS zuletzt, damit Ihre Änderungen greifen.

Die Liste styles ersetzt die des Parent-Themes, sie wird nicht erweitert. Fügen Sie daher immer das Stylesheet des Parent-Themes (css/styles.css) hinzu, sonst verliert Ihre Seite das Standard-Layout.

FreeMarker-Templates (.ftl-Dateien) benötigen Sie nur, wenn Sie die HTML-Struktur ändern möchten. Für Farben, Logos, Hintergründe, Texte und Sprachen ist keine Template-Anpassung nötig. Weitere Details finden Sie in der Keycloak-Themes-Dokumentation.

Java-Erweiterungen (Providers)

Das Verzeichnis providers/ ist für Funktionen gedacht, die Themes nicht abdecken: eigene Authenticatoren, User Storage, Event Listener oder Protocol Mapper.

Legen Sie Ihre .jar-Datei in diesem Verzeichnis ab und starten Sie Ihren Service neu. Dieser Neustart dauert etwas länger (ca. eine Minute), da Keycloak sich neu baut, um die Erweiterung einzubinden. Um eine Erweiterung zu entfernen, löschen Sie die Datei und starten Sie erneut.

Sie können auch Theme-.jar-Dateien hier ablegen, aber für Themes ist themes/ vorzuziehen: Das erfordert keinen Rebuild und Sie können die Dateien anschließend bearbeiten.