Die Login-Seiten (Keycloak-Theme)

Worum es geht

Die Oberflächen von CodamAI haben keine eigene Login-Maske. Wer sich anmeldet, landet auf einer Seite von Keycloak. Wie Keycloak dorthin kommt, steht unter Anmelden im Browser. Hier geht es um die Seiten selbst: welche es gibt, wann sie erscheinen und wohin sie führen.

Ein Theme ist die Gestaltung dieser Seiten. Keycloak baut jede Seite aus einer Vorlage im Format FreeMarker (Dateiendung .ftl) und füllt sie mit Texten aus einer Sprachdatei. Das Theme von CodamAI heißt codamai und liegt im Repository hub-login.

Wie eine Seite aussieht

Jede Seite hat zwei Spalten:

• Links das eigentliche Formular: Überschrift, ein kurzer Einleitungssatz, die Felder, Meldungen und Knöpfe.
• Rechts eine Produktfläche mit Hintergrundbild, den CodamAI-Modulen und kurzen Nutzenaussagen.

Alle Texte stehen in messages_de.properties und messages_en.properties, auch die der Produktfläche. Eine Sprachauswahl erscheint oben im Formular, sobald im Realm die Internationalisierung eingeschaltet ist und mehr als eine Sprache angeboten wird.

Das Theme erbt vom Standard-Theme keycloak (parent=keycloak). Seiten, die es nicht selbst gestaltet, etwa Passkeys (WebAuthn), das Einrichten eines Einmalcodes oder „Profil vervollständigen“, kommen deshalb mit dem Standard-Aufbau von Keycloak, eingebettet in den Rahmen von CodamAI.

Die Seitenkarte

flowchart TD
    APP["Oberfläche<br/>/login"] --> L["Anmelden<br/>login.ftl"]
    L -- "Passwort richtig" --> OTP{"zweiter Faktor<br/>eingerichtet?"}
    OTP -- ja --> O["Einmalcode<br/>login-otp.ftl"]
    OTP -- nein --> PA{"Pflichtaktion<br/>offen?"}
    O --> PA
    PA -- "Passwort setzen" --> UP["Neues Passwort<br/>login-update-password.ftl"]
    PA -- "E-Mail bestätigen" --> VE["E-Mail bestätigen<br/>login-verify-email.ftl"]
    PA -- keine --> BACK["zurück zur Oberfläche<br/>mit Code"]
    UP --> BACK
    VE --> BACK
    L -- "Link „Passwort vergessen“" --> RP["Passwort vergessen<br/>login-reset-password.ftl"]
    RP --> MAIL["Mail von Keycloak<br/>mit Link"]
    MAIL --> UP
    L -. "zu lange offen" .-> EX["Seite abgelaufen<br/>login-page-expired.ftl"]
    EX --> L

Lies es so: Die Anmeldung beginnt immer auf der Oberfläche, die auf /login automatisch zu Keycloak weiterleitet. Nach Passwort und gegebenenfalls Einmalcode prüft Keycloak, ob für das Konto noch eine Pflichtaktion offen ist. Eine Pflichtaktion (englisch required action) ist ein Schritt, den Keycloak vor dem ersten Zugang verlangt, etwa „Passwort setzen“. Erst wenn nichts mehr offen ist, schickt Keycloak die Person mit dem Einmalcode zurück zur Oberfläche.

Welche Seite wann kommt

OTP heißt One-Time Password: ein Code aus einer Authenticator-App, der nur einmal und kurz gilt.

Was die Realm-Einstellungen zeigen oder verstecken

Einige Elemente der Seiten hängen an Schaltern im Realm. Das Theme fragt sie ab und zeigt das Element nur, wenn der Schalter an ist.

Die zweite Spalte zeigt die Realm-Datei, die cias-runtime unter deploy/keycloak/import/ mitbringt. Eine andere Installation kann jeden Schalter anders setzen.

Die Ausprägungen

Das Theme in Keycloak einbinden

Das Theme ist statisch: FreeMarker-Vorlagen, Sprachdateien, ein Stylesheet und ein kleines Skript (Passwort anzeigen, Sprachmenü). Das Stylesheet resources/css/styles.css wird mit Tailwind aus src/main.css gebaut (npm run build).

1. Den Ordner theme/codamai in das Theme-Verzeichnis von Keycloak legen (/opt/keycloak/themes/codamai).
2. Im Realm unter Realm-Einstellungen → Themes → Login-Theme codamai auswählen.

Die Realm-Datei aus cias-runtime legt kein Login-Theme fest. Ohne diese Auswahl zeigt Keycloak seine Standardseiten, der Ablauf ist derselbe.

Fallen

Weiter

• Anmelden im Browser
• Das Passwort setzen
• Registrieren und Bestätigen
• Abmelden