259 lines
8.6 KiB
Markdown
259 lines
8.6 KiB
Markdown
# 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 |
|