claude_settings/plans/distributed-snacking-lighthouse.md

Plan: Passkey-UX, Keycloak-Theme & Redirect-Optimierung

Ziel

1. Passkey-Registrierung optional und einfach zugänglich machen
2. Keycloak Login-Seite pixel-perfekt wie Nextcloud aussehen lassen
3. Health-Check-Redirect beschleunigen (Timeout 3s → 1s)

Umgebung (Bestand)

Komponente	Details
Keycloak	v25.0, srvdocker02 (10.0.0.48:8180), Realm egonetix
Browser-Flow	browser-passkey (aktiv), inkl. WebAuthn Passwordless (ALTERNATIVE)
Nextcloud	v30.0.17, srvdocker02, oidc_auto_login App mit Health-Check
Docker-Compose Keycloak	/home/icke/keycloak/docker-compose.yml
Docker-Compose Nextcloud	/home/icke/nextcloud/docker-compose.yml
Nextcloud Repo	/home/rwiegand/Nextcloud/egonetix/nextcloud/
Infrastructure Repo	/home/rwiegand/Nextcloud/egonetix/infrastructure/

---

Schritt 1: Health-Check Timeout reduzieren

Datei: /home/rwiegand/Nextcloud/egonetix/nextcloud/oidc_auto_login/lib/Controller/HealthController.php

Änderung:

// Zeile 55: timeout von 3 auf 1 reduzieren
$response = $client->get($discoveryUri, ['timeout' => 1]);

Dann auf srvdocker02 deployen:

scp oidc_auto_login/lib/Controller/HealthController.php root@10.0.0.48:/home/icke/nextcloud/oidc_auto_login/lib/Controller/

Auswirkung: Normal <200ms (Cache-Hit), Cache-Miss ~300ms, Keycloak-Down 1s statt 3s.

---

Schritt 2: Nextcloud Login-Seite analysieren

Bevor ich das Theme baue, muss ich die exakte Nextcloud Login-Seite erfassen:

1. https://nextcloud.egonetix.de/login?direct=1 fetchen → HTML-Struktur, CSS-Klassen, Layout extrahieren
2. Nextcloud-CSS analysieren: Hintergrund, Farben, Fonts, Input-Styles, Button-Styles, Abstände
3. Logo-URL und -Größe bestimmen
4. Screenshot als Referenz nutzen (User liefert oder ich fetch die Seite)

Erwartete Nextcloud-Design-Tokens:

• Primärfarbe: #0082C9
• Font: Inter / System-Fonts
• Hintergrund: Gradient oder Custom Background Image
• Login-Box: Zentrierte Card, abgerundete Ecken
• Inputs: Heller Rahmen, Padding, volle Breite
• Button: Blau (#0082C9), weiße Schrift, volle Breite

---

Schritt 3: Keycloak Custom Theme erstellen

Verzeichnisstruktur auf srvdocker02

/home/icke/keycloak/themes/nextcloud/
└── login/
    ├── theme.properties         ← Parent-Theme + CSS-Imports
    ├── login.ftl                ← Login-Formular (Nextcloud-Layout)
    ├── template.ftl             ← Base-Template (HTML-Rahmen)
    ├── webauthn-authenticate.ftl ← Passkey-Login-Seite (Nextcloud-Look)
    ├── webauthn-register.ftl    ← Passkey-Registrierung (Nextcloud-Look)
    ├── messages/
    │   └── messages_de.properties ← Deutsche Texte
    └── resources/
        ├── css/
        │   └── nextcloud.css    ← Pixel-perfekte Nextcloud-Styles
        └── img/
            └── logo.svg         ← Nextcloud-Logo

theme.properties

parent=keycloak.v2
import=common/keycloak
styles=css/nextcloud.css

Erbt alle Templates von keycloak.v2, überschreibt nur CSS und die Templates die wir anpassen.

login.ftl (Kern-Template)

Pixel-perfekte Nachbildung der Nextcloud Login-Seite:

• Gleicher Hintergrund (Gradient/Bild)
• Zentrierte Login-Card
• Nextcloud-Logo oben
• Username + Password Inputs im Nextcloud-Stil
• Blauer Login-Button
• "Passkey einrichten" Link unten (→ Account Console)
• Social Provider (WebAuthn Passwordless) als "Mit Passkey anmelden" Button

webauthn-authenticate.ftl

Passkey-Login im Nextcloud-Stil:

• Gleicher Hintergrund und Card-Layout
• "Mit Passkey anmelden" Prompt
• "Andere Methode wählen" Link zurück zum Passwort-Formular

webauthn-register.ftl

Passkey-Registrierung im Nextcloud-Stil (für optionale Account-Console-Registrierung):

• Gleicher Look
• Klare Anweisungen auf Deutsch

nextcloud.css

Überschreibt die PatternFly-Styles von keycloak.v2:

• --pf-global--primary-color: #0082C9
• Background: Nextcloud-Gradient
• Card-Styling: Match Nextcloud login box
• Input-Styling: Match Nextcloud inputs
• Button-Styling: Match Nextcloud buttons
• Font: Inter / System-Fonts
• Alle Abstände und Radien angepasst

messages_de.properties

Deutsche Übersetzungen:

• loginTitle=Anmelden
• usernameOrEmail=Benutzername oder E-Mail
• password=Passwort
• doLogIn=Anmelden
• webauthn-passwordless-login-title=Mit Passkey anmelden
• webauthn-passwordless-register-title=Passkey einrichten

---

Schritt 4: Docker-Compose anpassen (srvdocker02)

Datei: /home/icke/keycloak/docker-compose.yml

Volume-Mount hinzufügen:

services:
  keycloak:
    volumes:
      - ./themes:/opt/keycloak/themes:ro

Theme-Verzeichnis erstellen und Theme-Dateien deployen:

mkdir -p /home/icke/keycloak/themes/nextcloud/login/resources/{css,img}
mkdir -p /home/icke/keycloak/themes/nextcloud/login/messages

Container neu starten: docker compose up -d

---

Schritt 5: Keycloak Realm konfigurieren

Login-Theme setzen

curl -X PUT ".../admin/realms/egonetix" \
  -d '{"loginTheme": "nextcloud"}'

Account Console Theme (optional)

Falls Account Console auch angepasst werden soll (für Passkey-Registrierung):

curl -X PUT ".../admin/realms/egonetix" \
  -d '{"accountTheme": "nextcloud"}'

---

Schritt 6: Optionale Passkey-Registrierung

Ansatz: Self-Service über Account Console + Hinweis auf Login-Seite

1. Login-Seite (login.ftl): Kleiner Hinweis-Link am Ende:

   "Tipp: Passkey einrichten für schnelleren Login"

   Dieser Link führt zu https://auth.egonetix.de/realms/egonetix/account/#/security/signingin

2. Account Console: User kann dort unter "Signing In" → "Set up Passwordless" einen Passkey registrieren

   • Bitwarden Browser-Extension fängt den WebAuthn-Request ab → Passkey in Bitwarden
   • "Dieses Gerät" / Platform Authenticator → Fingerabdrucksensor

3. Kein Zwang: defaultAction bleibt false. Kein User wird gezwungen.

4. Admin-Option für Zukunft: Falls einzelne User den Passkey einrichten SOLLEN:

   curl -X PUT ".../admin/realms/egonetix/users/{userId}" \
     -d '{"requiredActions": ["webauthn-register-passwordless"]}'
   

---

Schritt 7: Testen

Test	Erwartung
Nextcloud öffnen → Auto-Redirect	Redirect in <200ms (Cache-Hit)
Keycloak Login-Seite	Sieht aus wie Nextcloud
Login mit Passwort	Funktioniert, Redirect zurück zu Nextcloud
"Mit Passkey anmelden" Button	Zeigt Browser-Passkey-Dialog
Passkey in Account Console registrieren	Bitwarden/Fingerprint funktioniert
Login mit Passkey	Direkt-Login ohne Passwort
Keycloak stoppen → LDAP-Fallback	Health-Check: 1s Timeout, dann normales Login
?direct=1	Admin-Fallback funktioniert
Mobile Apps	Nicht betroffen

---

Schritt 8: Dokumentation

Nextcloud Repo (/home/rwiegand/Nextcloud/egonetix/nextcloud/)

• README.md: Passkey-Dokumentation + Theme-Info ergänzen

Infrastructure Repo (/home/rwiegand/Nextcloud/egonetix/infrastructure/)

• keycloak-sso.md: Passkey-Konfiguration + Theme-Dokumentation
• hosts/srvdocker02.md: Theme-Volume-Mount dokumentieren

---

Risiken

Risiko	Mitigation
Theme-Fehler → Login-Seite kaputt	Theme erbt von keycloak.v2, Fallback auf Parent
WebAuthn nicht verfügbar (alter Browser)	Passwort-Login bleibt immer verfügbar
Keycloak-Restart nötig nach Theme-Änderung	Im Wartungsfenster oder akzeptabel (paar Sekunden)
CSS-Konflikte mit Keycloak Updates	Theme basiert auf CSS-Overrides, nicht auf Template-Hacks

---

Dateien-Übersicht

Datei	Aktion	Ort
HealthController.php	Timeout 3→1	Nextcloud Repo + srvdocker02
themes/nextcloud/login/theme.properties	Neu	srvdocker02
themes/nextcloud/login/login.ftl	Neu	srvdocker02
themes/nextcloud/login/template.ftl	Neu	srvdocker02
themes/nextcloud/login/webauthn-authenticate.ftl	Neu	srvdocker02
themes/nextcloud/login/webauthn-register.ftl	Neu	srvdocker02
themes/nextcloud/login/messages/messages_de.properties	Neu	srvdocker02
themes/nextcloud/login/resources/css/nextcloud.css	Neu	srvdocker02
themes/nextcloud/login/resources/img/logo.svg	Neu	srvdocker02
docker-compose.yml (Keycloak)	Volume-Mount	srvdocker02
Keycloak Realm API	loginTheme setzen	API
README.md	Aktualisieren	Nextcloud Repo
keycloak-sso.md	Aktualisieren	Infrastructure Repo
hosts/srvdocker02.md	Aktualisieren	Infrastructure Repo