From 77e30e268b17babd9d1846e372fd78579285342f Mon Sep 17 00:00:00 2001 From: Kroonk Date: Thu, 21 May 2026 11:42:28 +0200 Subject: [PATCH] docs: update Brain.md with SSO integration details and troubleshooting hypotheses --- Brain.md | 68 +++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 58 insertions(+), 10 deletions(-) diff --git a/Brain.md b/Brain.md index 31238c9..8f5fbbb 100644 --- a/Brain.md +++ b/Brain.md @@ -111,17 +111,65 @@ MiChess = Lichess-inspirierte Schachplattform, self-hosted auf einer NAS, in Doc ## Lessons Learned -*(wird im Verlauf befüllt)* +- **CSS-only Dropdowns vs. Autofill Extensions:** Rein CSS-basierte DaisyUI Dropdowns (`dropdown-content` getriggert über `:focus`/`tabIndex`) schließen sich unkontrolliert, wenn Passwort-Manager (z.B. Vaultwarden) Fokus-Events abfangen oder Overlays einblenden. Lösung: Vollständig React-gesteuerter Dropdown-Zustand (`useState`, `useRef`, `click-outside` via `mousedown` auf Dokumentenebene) ohne `tabIndex={0}`. +- **Docker Env Mapping Empty Strings:** Im `docker-compose.yml` sorgt die Syntax `SSO_CLIENT_ID: ${SSO_CLIENT_ID:-}` dafür, dass bei Auslassung der Variablen in der `.env`-Datei ein leerer String (`""`) in die Node.js-Umgebung gereicht wird. Node.js interpretiert `""` als *falsy*, wodurch Abfragen wie `process.env.SSO_CLIENT_ID` fehlschlagen. --- -## Nächste Schritte (immer aktuell) +## 🔑 Keycloak SSO Integration & UX Overhaul -1. Git remote setzen → push -2. Umbenennen chessu → MiChess -3. DB-Schema erweitern -4. Stockfish backend einbauen -5. Admin-Panel UI + Backend -6. Friends-System -7. Docker finalisieren -8. Issues aus Git bearbeiten +### 1. Backend-Erweiterungen (Server) +- **Paket:** `openid-client` für OIDC-Standard-Interaktionen. +- **Endpunkte (`/v1/auth/sso/*`):** + - `GET /v1/auth/sso/config`: Gibt `{ enabled: boolean }` zurück. Erkennt SSO als aktiv, sobald `SSO_CLIENT_SECRET` gesetzt ist (die optionalen Variablen `SSO_CLIENT_ID` und `SSO_AUTHORITY` haben Code-Fallbacks). + - `GET /v1/auth/sso/login`: Initiiert den OIDC-Flow und leitet zur Keycloak Realm `mischlabs` weiter. + - `GET /v1/auth/sso/callback`: Verarbeitet das authorization code grant, erfragt User-Infos und führt **Just-In-Time (JIT) Provisionierung** durch. +- **Option A Permission Mapping:** JIT-provisionierte Benutzer werden automatisch zu `admin` befördert, wenn ihr Benutzername `MrDiderot` lautet oder wenn die Benutzer-Datenbank leer ist (andernfalls Rolle `user`). + +### 2. Frontend-Umbau (Client) +- **Popup-Entfernung:** `AuthModal.tsx` wurde komplett gelöscht. Es gibt beim Laden der Seite kein störendes Popup mehr. +- **Avatar-Dropdown:** Einbettung von `AuthDropdownContent.tsx` in `Header.tsx` für unangekündigte Gäste. Bietet Reiter für *Gast*, *Anmelden*, *Registrieren* sowie die Keycloak-Schaltfläche (wenn aktiviert). +- **Passwort-Manager-Immunisierung:** Vollständig React-kontrolliertes Dropdown gegen vorzeitiges Schließen beim Autofill. + +--- + +## 🔍 Fehleranalyse: SSO-Schaltfläche fehlt weiterhin + +Obwohl das Frontend-Update aktiv ist (Vaultwarden-Anmeldung schließt das Fenster nicht mehr), wird die Schaltfläche `"Anmelden mit Keycloak"` nicht angezeigt. Das bedeutet, dass der Client `ssoEnabled === false` setzt, weil der API-Call `${API_URL}/v1/auth/sso/config` nicht `{ enabled: true }` zurückgibt. + +### 📋 Vermutungen und Diagnose-Ansätze (für Zweit-KI / Debugging) + +#### Vermutung A: Die Umgebungsvariable `SSO_CLIENT_SECRET` ist im Backend-Container nicht geladen. +- **Grund:** Die Variable wurde in `/volume2/docker/mischlabs/.env` eingetragen, aber Docker Compose hat den Container nicht vollständig mit der neuen Umgebung neu generiert. +- **Diagnose:** SSH-Zugriff auf das NAS und Ausführen von: + ```bash + docker exec -it michess env | grep SSO + ``` + Wenn hier `SSO_CLIENT_SECRET` fehlt oder leer ist, lädt der Container die Variable nicht. +- **Behebung:** Den Container zwingend neu erstellen lassen, nicht nur updaten: + ```bash + docker compose down && docker compose up -d + ``` + +#### Vermutung B: Abweichende `.env`-Pfade oder fehlendes Volume-Mapping. +- **Grund:** Im Docker-Compose-Setup wird `SSO_CLIENT_SECRET` über `${SSO_CLIENT_SECRET:-}` zugewiesen. Wenn die `.env`-Datei nicht im selben Verzeichnis wie `docker-compose.yml` liegt oder Docker Compose sie nicht standardmäßig lädt, bleibt der Wert leer. +- **Diagnose:** Prüfen, ob die Variable auf dem Docker-Host in der `.env` existiert: + ```bash + cat /volume2/docker/mischlabs/.env | grep SSO + ``` + +#### Vermutung C: Netzwerkanfrage / CORS / SSL-Fehler beim Config-Call. +- **Grund:** Die Web-App (`https://michess.mischlabs.de`) versucht den Status von `https://michess-api.mischlabs.de/v1/auth/sso/config` abzufragen. Es könnte sein, dass dieser API-Call fehlschlägt (z.B. durch CORS-Sicherheitsrichtlinien, Cloudflare-Tunnel blockiert Requests mit Credentials, oder Mixed-Content-Fehler). +- **Diagnose:** + 1. Öffne die Entwicklerkonsole des Browsers (F12) -> **Netzwerk-Tab (Network)**. + 2. Lade die Seite neu und filtere nach `config` oder `sso`. + 3. Prüfe den HTTP-Statuscode und die Antwort von `https://michess-api.mischlabs.de/v1/auth/sso/config`. + 4. Kommt dort `{ "enabled": false }` zurück (dann ist es **Vermutung A/B**), oder scheitert der Request komplett (CORS/Netzwerkfehler)? + +--- + +## Nächste Schritte + +1. Prüfe die Browser-Konsole im Netzwerk-Tab, um zu sehen, ob die API-Antwort `{ enabled: false }` liefert oder blockiert wird. +2. Führe auf dem NAS `docker exec -it michess env | grep SSO` aus, um die Live-Umgebungsvariablen zu validieren. +3. Führe einen sauberen Docker-Neustart aus (`docker compose down && docker compose up -d`).