Pitfalls: /etc/hosts verboten, Split-Horizon-DNS bei UCS, Proxmox VMID-Wechsel
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
root
258
plans/distributed-snacking-lighthouse.md
Normal file
258
plans/distributed-snacking-lighthouse.md
Normal file
@@ -0,0 +1,258 @@
|
||||
# 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 |
|
||||
Reference in New Issue
Block a user