docs: add oidc validation runbook

CHANGELOG.md

@@ -10,6 +10,8 @@ By: Codex (GPT-5)
 | 28.12.2025 | 🏗️ Planning | ID: EPIC_000007 und US_000020-US_000023 dokumentiert. By: Codex (GPT-5) |
 | 28.12.2025 | 🏗️ Planning | ID: US_000024 dokumentiert; OIDC- und Login-Stories praezisiert. By: Codex (GPT-5) |
 | 28.12.2025 | 🏗️ Planning | ID: US_000024 Theme-Assets unter assets/design vorbereitet. By: Codex (GPT-5) |
+| 28.12.2025 | 🏗️ Planning | ID: US_000025 und TASK_000025-TASK_000026 fuer OIDC-Validierung gestartet. By: Codex (GPT-5) |
+| 28.12.2025 | 📝 Req | ID: US_000025 Runbook/Validierungsschritte dokumentiert. By: Codex (GPT-5) |
 
 ---
 ## Legende

README.md

@@ -16,7 +16,7 @@ cd /opt/sk
 ./scripts/install.sh
 sudo systemctl status skd.service
 ```
-Then open `http://localhost:8000/` and set the API token in the UI.
+Then open `http://localhost:8000/` and log in via PAM (default) to start quickly.
 
 ## Configuration
 Set in `/etc/skd/env` (see `env.example`):
@@ -34,6 +34,31 @@ Set in `/etc/skd/env` (see `env.example`):
 Notes:
 - `./scripts/install.sh` will create `/etc/skd/env` from `env.example` if missing (edit afterwards) and ensure the `skd` service user/group exist.
 
+## OIDC Setup
+OIDC ist optional. Wenn der Provider noch nicht bereit ist, bleibe bei `SKD_AUTH_MODE=pam`.
+1. Issuer muss der externen URL des Providers entsprechen (TLS trust erforderlich).
+2. OIDC Client registrieren (DCR), z.B.:
+```bash
+export SKD_OIDC_ISSUER="https://auth.example.org"
+export SKD_OIDC_REDIRECT_URI="https://<device-host>[:port]/login/oidc/callback"
+export OIDC_INITIAL_ACCESS_TOKEN="<initial-access-token>"
+./scripts/register_oidc_client.sh
+```
+3. Danach in `/etc/skd/env` setzen:
+```
+SKD_AUTH_MODE=oidc
+SKD_OIDC_ISSUER=...
+SKD_OIDC_CLIENT_ID=...
+SKD_OIDC_CLIENT_SECRET=...
+SKD_OIDC_REDIRECT_URI=...
+SKD_OIDC_SCOPES=openid profile email
+SKD_SESSION_COOKIE_SECURE=true
+```
+Hinweise:
+- Redirect-URI muss exakt sein (keine Wildcards).
+- Bei Host/Port-Aenderung neu registrieren und neue Credentials setzen.
+- Allowlist fuer OIDC: `SKD_AUTH_ALLOWED_USERS` prueft `preferred_username`, `email` oder `sub`.
+
 ## Running
 - Service: managed by systemd; `./scripts/install.sh` writes the unit dynamically to `/etc/systemd/system/skd.service` with the current repo path and restarts it.
 - Manual run: `./scripts/run.sh` (uses `.venv`, defaults to `0.0.0.0:8000`).
@@ -41,6 +66,12 @@ Notes:
 - Login (OIDC): open `http://localhost:8000/login/oidc/start` → provider → redirected back with session cookie set.
 - Health: `curl -H "Authorization: Bearer <token>" http://localhost:8000/health`
 
+## OIDC Validation & Fallbacks
+- Validierungsschritte: `docs/oidc-validation.md` (State, Token-Exchange, Claims, Cookie).
+- Falls Discovery/JWKS nicht verfuegbar: OIDC deaktivieren und PAM nutzen.
+- Falls DCR nicht verfuegbar: Client manuell im IdP anlegen und `SKD_OIDC_*` setzen.
+- Bei Self-Signed TLS: CA im System trusten oder in Dev PAM nutzen.
+
 ## API (Bearer token via `/login`)
 - `GET /users` → `[{user, logged_in}]` (manageable system users; excludes root)
 - `POST /users/{name}/disable` with JSON `{countdown?, sound?, message?}`

docs/oidc-validation.md

@@ -0,0 +1,38 @@
+ID: DOC_000003 | Version: 0.1.0 | Status: Draft
+By: Codex (GPT-5)
+
+# OIDC End-to-End Validation (Kiddo)
+
+## Purpose
+Validiere den OIDC-Login-Flow gegen einen realen oder Stub-Provider und dokumentiere Ergebnisse.
+
+## Preconditions
+- Kiddo laeuft und ist erreichbar (z.B. `http://localhost:8000`).
+- OIDC Provider oder Stub erreichbar.
+- `SKD_AUTH_MODE=oidc` und `SKD_OIDC_*` gesetzt.
+- Redirect-URI: `https://<device-host>[:port]/login/oidc/callback` ist registriert.
+
+## Validation Steps
+1. OIDC Start
+   - Aufruf: `GET /login/oidc/start`
+   - Erwartet: Redirect zum Provider, State-Cookie gesetzt.
+2. Callback
+   - Provider ruft `GET /login/oidc/callback?code=...&state=...` auf.
+   - Erwartet: State valid, Token-Exchange erfolgreich, Session-Cookie gesetzt, Redirect `/`.
+3. Session Check
+   - Aufruf: `GET /me` mit Cookie oder Bearer.
+   - Erwartet: `user` und `auth_mode=oidc`.
+4. Allowlist
+   - Falls `SKD_AUTH_ALLOWED_USERS` gesetzt: nicht erlaubte User werden mit 403 abgewiesen.
+
+## Results
+- Datum:
+- Provider:
+- Host/Redirect:
+- Ergebnis:
+- Fehlerbilder:
+
+## Fallbacks bei unvollstaendigem IdP
+- Discovery/JWKS fehlt: OIDC deaktivieren und PAM nutzen.
+- DCR fehlt: Client manuell im IdP anlegen und `SKD_OIDC_*` setzen.
+- TLS-Probleme: CA trusten oder PAM fuer Dev nutzen.

project-management/PROJECT_STATUS.md

@@ -45,6 +45,9 @@ Sicheres, remote steuerbares System zum Sperren/Entsperren lokaler Nutzerkonten.
 - [x] TASK_000008: OIDC auth callback
 - [x] US_000009: Autorisierung und /me-Identitaet
 - [x] TASK_000009: Authorization /me gate
+- [ ] US_000025: OIDC End-to-End Validierung und Runbook
+- [ ] TASK_000025: OIDC E2E validation
+- [ ] TASK_000026: OIDC runbook update
 
 ### EPIC_000004: Web UI
 - [x] US_000010: Index-Seite ausliefern

project-management/requirements/epics/EPIC_000003.md

@@ -34,7 +34,8 @@ Stelle einen sicheren Admin-Login bereit, der Token oder Session-Cookies ausstel
 - Abhaengigkeit von PAM und OIDC-Provider-Verfuegbarkeit.
 - Cookie-Sicherheit muss korrekt konfiguriert sein.
 
-## Zugeordnete User Stories (Done)
+## Zugeordnete User Stories
 - US_000007: PAM-Login mit Token
 - US_000008: OIDC-Login Flow
 - US_000009: Autorisierung und /me-Identitaet
+- US_000025: OIDC End-to-End Validierung und Runbook

project-management/requirements/stories/US_000025.md

@@ -0,0 +1,19 @@
+ID: US_000025 | Version: 0.1.0 | Status: Draft
+By: Codex (GPT-5)
+
+# US_000025: OIDC End-to-End Validierung und Runbook
+
+Status: Draft
+
+Als Betreiber moechte ich den OIDC-Login Ende-zu-Ende validieren und dokumentieren, damit der Betrieb auch mit einem noch nicht vollstaendigen IdP planbar ist.
+
+## Akzeptanzkriterien
+- Given ein erreichbarer OIDC-Provider oder ein Stub/Test-Provider
+- When der OIDC-Flow ueber `/login/oidc/start` und `/login/oidc/callback` durchlaufen wird
+- Then Login, Token-Validierung und Session-Cookie werden erfolgreich nachvollzogen
+- And die erforderlichen ENV-Variablen und Redirect-URIs sind im Runbook dokumentiert
+- And Fallback-Optionen fuer nicht verfuegbare OIDC-Funktionen sind beschrieben
+
+## Task-Platzhalter
+- TASK_000025: OIDC E2E validation (Details bei Story-Start)
+- TASK_000026: OIDC runbook update (Details bei Story-Start)

project-management/requirements/tasks/TASK_000025.md

@@ -0,0 +1,20 @@
+ID: TASK_000025 | Version: 0.1.0 | Status: Draft
+By: Codex (GPT-5)
+
+# TASK_000025: OIDC E2E validation
+
+## Outcome
+OIDC-Login Flow ist Ende-zu-Ende gegen einen realen oder Stub-Provider verifiziert.
+
+## Story-Bezug
+US_000025
+
+## Beschreibung
+- Teste `/login/oidc/start` und `/login/oidc/callback` mit einem Provider (oder Stub).
+- Validierung: State, Token-Exchange, Claims, Allowlist, Session-Cookie.
+- Dokumentiere Abweichungen bei nicht verfuegbaren IdP-Funktionen.
+- Testplan liegt in `docs/oidc-validation.md`.
+
+## Definition of Done (DoD)
+- Testschritte sind dokumentiert.
+- Ergebnisse inklusive Fehlerbilder sind festgehalten.

project-management/requirements/tasks/TASK_000026.md

@@ -0,0 +1,20 @@
+ID: TASK_000026 | Version: 0.1.0 | Status: Draft
+By: Codex (GPT-5)
+
+# TASK_000026: OIDC runbook update
+
+## Outcome
+Runbook beschreibt OIDC-Setup, Redirect-URIs und Fallbacks fuer einen nicht vollstaendigen IdP.
+
+## Story-Bezug
+US_000025
+
+## Beschreibung
+- Ergaenze README mit klaren OIDC-ENV-Beispielen.
+- Beschreibe exakte Redirect-URI und Host/Port-Wechsel.
+- Fuege Fallbacks hinzu (PAM-Login, Hinweise zu fehlenden IdP-Features).
+- Verweise auf `docs/oidc-validation.md` fuer die Testschritte.
+
+## Definition of Done (DoD)
+- README enthaelt konkrete OIDC-Setup-Schritte.
+- Fallbacks sind fuer Operatoren nachvollziehbar.