docs: add oidc validation runbook

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?}`