From a9c57caaf14baf5f6922942b853a0b4dc5878af5 Mon Sep 17 00:00:00 2001 From: stephan Date: Sun, 28 Dec 2025 13:20:59 +0100 Subject: [PATCH] docs: add oidc validation runbook --- CHANGELOG.md | 2 + README.md | 33 +++++++++++++++- docs/oidc-validation.md | 38 +++++++++++++++++++ project-management/PROJECT_STATUS.md | 3 ++ .../requirements/epics/EPIC_000003.md | 3 +- .../requirements/stories/US_000025.md | 19 ++++++++++ .../requirements/tasks/TASK_000025.md | 20 ++++++++++ .../requirements/tasks/TASK_000026.md | 20 ++++++++++ 8 files changed, 136 insertions(+), 2 deletions(-) create mode 100644 docs/oidc-validation.md create mode 100644 project-management/requirements/stories/US_000025.md create mode 100644 project-management/requirements/tasks/TASK_000025.md create mode 100644 project-management/requirements/tasks/TASK_000026.md diff --git a/CHANGELOG.md b/CHANGELOG.md index f17345e..1c6b838 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index be19f2f..c5517c0 100644 --- a/README.md +++ b/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://[:port]/login/oidc/callback" +export OIDC_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 " 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?}` diff --git a/docs/oidc-validation.md b/docs/oidc-validation.md new file mode 100644 index 0000000..a9f323f --- /dev/null +++ b/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://[: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. diff --git a/project-management/PROJECT_STATUS.md b/project-management/PROJECT_STATUS.md index 5377483..17fcd7c 100644 --- a/project-management/PROJECT_STATUS.md +++ b/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 diff --git a/project-management/requirements/epics/EPIC_000003.md b/project-management/requirements/epics/EPIC_000003.md index e3802ef..c92f9fe 100644 --- a/project-management/requirements/epics/EPIC_000003.md +++ b/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 diff --git a/project-management/requirements/stories/US_000025.md b/project-management/requirements/stories/US_000025.md new file mode 100644 index 0000000..3304951 --- /dev/null +++ b/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) diff --git a/project-management/requirements/tasks/TASK_000025.md b/project-management/requirements/tasks/TASK_000025.md new file mode 100644 index 0000000..7fef59f --- /dev/null +++ b/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. diff --git a/project-management/requirements/tasks/TASK_000026.md b/project-management/requirements/tasks/TASK_000026.md new file mode 100644 index 0000000..d670218 --- /dev/null +++ b/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.