# 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:
```php
// Zeile 55: timeout von 3 auf 1 reduzieren
$response = $client->get($discoveryUri, ['timeout' => 1]);
```

Dann auf srvdocker02 deployen:
```bash
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

```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:
```yaml
services:
  keycloak:
    volumes:
      - ./themes:/opt/keycloak/themes:ro
```

Theme-Verzeichnis erstellen und Theme-Dateien deployen:
```bash
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

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

### Account Console Theme (optional)

Falls Account Console auch angepasst werden soll (für Passkey-Registrierung):
```bash
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](account-console-url) 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:
   ```bash
   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 |