Zum Inhalt

Themes mit Keycloakify

Ziel

In dieser Aufgabe passen Sie das Erscheinungsbild von Keycloak an, indem Sie das Keycloakify-Starter-Projekt verwenden. Sie werden:

  • das Keycloakify-Starter-Projekt aufsetzen
  • CSS-Änderungen an der Login-Seite vornehmen
  • eine vollständige Seite aus dem Theme herauslösen und anpassen
  • ein fertiges Keycloak-Theme als JAR bauen

Hilfsmittel

  • Versuchen Sie, die unten stehenden Aufgaben mit Hilfe der Folien eigenständig zu lösen.
  • Sollten Sie dabei Probleme haben, finden Sie bei jeder Aufgabe einen ausklappbaren Block, in dem der Lösungsweg beschrieben wird.

Aufgabe 1 - Keycloakify aufsetzen

1.1: Repository klonen und Abhängigkeiten installieren

Klonen Sie das offizielle Keycloakify-Starter-Repository nach /home/coder/workspace/kc-lab/keycloakify-starter und installieren Sie die npm-Abhängigkeiten.

Lösung (Klicken Sie auf den Pfeil, falls Sie nicht weiterkommen)
  • Führen Sie folgende Befehle im Terminal aus: 
    cd /home/coder/workspace
mkdir kc-lab
cd kc-lab/
git clone https://github.com/keycloakify/keycloakify-starter
cd keycloakify-starter/
npm install

1.2: Projektstruktur erkunden

Verschaffen Sie sich einen Überblick über die Projektstruktur. Machen Sie sich insbesondere mit dem Ordner src/login/ vertraut.

Lösung (Klicken Sie auf den Pfeil, falls Sie nicht weiterkommen)
  • Geben Sie die Verzeichnisstruktur im Terminal aus: 
    tree -I node_modules .
  • Schauen Sie sich src/login/KcPage.tsx an – das ist der Einstiegspunkt für das Login-Theme. Die Datei entscheidet anhand des kcContext.pageId, welche Seite gerendert wird.

Aufgabe 2 - Einfache CSS-Anpassungen

2.1: CSS-Datei anlegen

Erstellen Sie die Datei src/login/main.css mit folgendem Inhalt:

.kcFormHeaderClass {
    background: #1f2937;
    color: white;
    padding: 1rem;
    border-radius: 0.75rem;
}

.kcButtonPrimaryClass {
    background: #f9b233 !important;
    border-color: #f9b233 !important;
}

2.2: CSS-Datei einbinden

Importieren Sie die CSS-Datei in src/login/KcPage.tsx, damit sie beim Theme-Build berücksichtigt wird.

Lösung (Klicken Sie auf den Pfeil, falls Sie nicht weiterkommen)
  • Öffnen Sie src/login/KcPage.tsx und fügen Sie am Anfang der Datei folgenden Import hinzu: 
    import "./main.css";

Aufgabe 3 - Seite herauslösen (eject-page)

Keycloakify erlaubt es, einzelne Seiten vollständig zu überschreiben. Lösen Sie die Login-Seite heraus, um den gesamten React-Code der Seite direkt bearbeiten zu können.

3.1: Login-Seite herauslösen

Verwenden Sie den interaktiven Keycloakify-CLI-Befehl, um eine Seite herauszulösen, und wählen Sie Login.ftl.

Lösung (Klicken Sie auf den Pfeil, falls Sie nicht weiterkommen)
  • Führen Sie aus: 
    npx keycloakify eject-page
  • Wählen Sie im interaktiven Menü Login.ftl aus.
  • Keycloakify legt die Datei src/login/pages/Login.tsx an und registriert sie automatisch in KcPage.tsx.

3.2: Ergebnis ansehen

Öffnen Sie src/login/pages/Login.tsx und machen Sie sich mit dem Aufbau vertraut. Was unterscheidet die herausgelöste Seite von den Standard-Komponenten?

Lösung (Klicken Sie auf den Pfeil, falls Sie nicht weiterkommen)
  • Sie sehen den vollständigen React-Code der Login-Seite. Ab sofort wird Ihre lokale Datei anstelle der Keycloakify-Standardimplementierung verwendet.

Aufgabe 4 - Theme bauen und einbinden

4.1: Theme-JAR bauen

Bauen Sie das fertige Keycloak-Theme als JAR-Datei.

Lösung (Klicken Sie auf den Pfeil, falls Sie nicht weiterkommen)
  • Führen Sie aus: 
    npm run build-keycloak-theme
  • Nach dem Build finden Sie die JAR-Datei im Ordner dist_keycloak/.

4.2: Theme in Keycloak einbinden

Passen Sie die folgende docker-compose.yml so an, dass die gebaute JAR als Volume in den Keycloak-Container gemountet wird. Die JAR muss unter /opt/keycloak/providers/ im Container liegen.

Docker-compose-Datei
  • Erstellen Sie eine Datei docker-compose.yml im Ordner kc-lab/: 
    services:
    postgres:
        image: postgres
        environment:
            POSTGRES_USER: keycloak
            POSTGRES_PASSWORD: secret
            POSTGRES_DB: keycloak
    keycloak:
        image: quay.io/keycloak/keycloak:latest
        environment:
            KC_BOOTSTRAP_ADMIN_USERNAME: admin
            KC_BOOTSTRAP_ADMIN_PASSWORD: admin
            KC_DB: postgres
            KC_DB_URL_HOST: postgres
            KC_DB_USERNAME: keycloak
            KC_DB_PASSWORD: secret
        command:
        - start-dev
        - "--hostname=https://keycloak.<VSCode-URL>"
        - "--proxy-headers=xforwarded"
        depends_on: [ "postgres" ]
        labels:
        - "traefik.enable=true"
        - "traefik.http.routers.keycloak.rule=Host(`keycloak.<VSCode-URL>`)"
        - "traefik.http.services.keycloak.loadbalancer.server.port=8080"
        networks:
        - default
        - proxy
networks:
    proxy:
        external: true
  • Ersetzen Sie <VSCode-URL> durch Ihren Hostnamen (ohne https://).
Lösung (Klicken Sie auf den Pfeil, falls Sie nicht weiterkommen)
  • Fügen Sie dem keycloak-Service einen volumes-Eintrag hinzu: 
    volumes:
  - ./keycloakify-starter/dist_keycloak/keycloak-theme-for-kc-all-other-versions.jar:/opt/keycloak/providers/keycloakify-theme.jar
  • Starten Sie Keycloak mit: 
    cd /home/coder/workspace/kc-lab
docker compose up -d
  • Prüfen Sie unter Realm Settings → Themes, ob das neue Theme in der Dropdown-Liste erscheint.