# OIDC Integration: OICD (IdP) + Kiddo (Clients)

## Herangehensweise und Gedankengang

Ziel war es, beide Projekte so zu verbinden, dass Kiddo OICD als OIDC-Provider nutzt, ohne Codeaenderungen vorzunehmen. Wir haben die vorhandenen Konfigurationspfade, DCR-Faehigkeiten und OIDC-Endpunkte geprueft und daraus die minimalen, operationalen Schritte abgeleitet.

Leitfragen, die wir dabei beantwortet haben:
- Welche Konfiguration erwartet Kiddo fuer OIDC (Issuer, Client, Redirect, Cookies)?
- Welche OIDC-Funktionen liefert OICD (Discovery, JWKS, DCR, Admin-UI)?
- Wo liegen die harten OIDC-Anforderungen (Issuer-Match, exakte Redirect-URIs, TLS-Vertrauen)?
- Wie kann die Registrierung skalieren, wenn Geraete und Redirects erst spaeter feststehen?

### OICD (IdP) - Herangehensweise
Wir haben in OICD geprueft, welche OIDC-Endpunkte vorhanden sind (Discovery, JWKS, Token, DCR) und wie der Issuer erzeugt wird. Entscheidend ist, dass der Issuer exakt der externen URL entspricht, unter der OICD erreichbar ist. Zudem gibt es eine Admin-Funktion zur Erzeugung von Initial-Access-Tokens, die den DCR-Flow ermoeglichen. Daraus folgt: Stabiler Issuer (prod/dev), TLS trust, und ein standardisierter Weg zur Token-Erzeugung fuer DCR.

### Kiddo (Client) - Herangehensweise
Wir haben in Kiddo geprueft, welche Umgebungsvariablen fuer OIDC benoetigt werden und wie die Claims interpretiert werden. Kiddo validiert ID-Tokens gegen den Issuer und JWKS und benoetigt exakte Redirect-URIs. Da die Device-Hosts dynamisch sind, ist DCR der beste Weg, pro Geraet eigene Clients zu registrieren, sobald die finale URL bekannt ist. Daraus folgen: pro Geraet DCR, danach Env-Setup, optional Allowlist fuer OIDC-User.

Aus diesen Punkten ergab sich der Weg: OICD stellt stabile Issuer-URLs bereit, Redirect-URIs muessen konkret registriert werden, und DCR (mit Initial-Access-Token) ist der beste Weg, um pro Geraet eigene Clients dynamisch zu erzeugen. Daraus wurden die Stories, Akzeptanzkriterien und das Provisioning-Kommando abgeleitet.

## Epic: OIDC-Login fuer Kiddo (Client-Seite)

### Story 1: Zentrales Provisioning registriert pro Geraet einen OIDC-Client
Als Provisioner moechte ich pro Geraet einen OIDC-Client via DCR anlegen, damit jedes Geraet einen eigenen Client-ID/Secret hat.

Acceptance Criteria:
- DCR-Call mit `SKD_OIDC_ISSUER`, `SKD_OIDC_REDIRECT_URI` und `OIDC_INITIAL_ACCESS_TOKEN` erzeugt `client_id` und `client_secret`.
- Redirect-URI ist exakt `https://<device-host>[:port]/login/oidc/callback` (keine Wildcards).

Referenzen:
- `kiddo/scripts/register_oidc_client.sh`

### Story 2: Kiddo-Geraet ist per OIDC konfiguriert
Als Geraetebetreiber moechte ich ein Kiddo-Geraet so konfigurieren, dass es sich ueber OICD authentifiziert.

Acceptance Criteria:
- `SKD_AUTH_MODE=oidc` ist gesetzt.
- `SKD_OIDC_ISSUER`, `SKD_OIDC_CLIENT_ID`, `SKD_OIDC_CLIENT_SECRET`, `SKD_OIDC_REDIRECT_URI` sind gesetzt.
- Bei HTTPS ist `SKD_SESSION_COOKIE_SECURE=true`.

Referenzen:
- `kiddo/env.example`
- `kiddo/README.md`
- `kiddo/backend/settings.py`

### Story 3: Zugriffskontrolle auf OIDC-Login
Als Betreiber moechte ich steuern, welche Benutzer sich via OIDC anmelden duerfen.

Acceptance Criteria:
- `SKD_AUTH_ALLOWED_USERS` schraenkt Zugriff ein, basierend auf `preferred_username` oder `email` oder `sub` aus dem ID-Token.

Referenzen:
- `kiddo/backend/oidc.py`
- `kiddo/backend/auth.py`

### Story 4: Betrieb mit wechselnden Geraeten (DCR-Flow)
Als Betreiber moechte ich neue Geraete spaeter onboarden koennen, ohne OICD manuell zu konfigurieren.

Acceptance Criteria:
- DCR-Prozess ist dokumentiert und kann pro Geraet wiederholt werden.
- Bei Host/Port-Aenderung erfolgt Neuregistrierung (neuer Client/Secret).

Referenzen:
- `kiddo/scripts/register_oidc_client.sh`

## DCR Kommando (zentral, pro Geraet)

Prod:
```bash
export SKD_OIDC_ISSUER="https://auth.wlkns.org"
export SKD_OIDC_REDIRECT_URI="https://<device-host>[:port]/login/oidc/callback"
export OIDC_INITIAL_ACCESS_TOKEN="<initial-access-token>"
/home/stephan/applications/wlkns/kiddo/scripts/register_oidc_client.sh
```

Dev:
```bash
export SKD_OIDC_ISSUER="https://dev.wlkns.org"
export SKD_OIDC_REDIRECT_URI="https://<device-host>[:port]/login/oidc/callback"
export OIDC_INITIAL_ACCESS_TOKEN="<initial-access-token>"
/home/stephan/applications/wlkns/kiddo/scripts/register_oidc_client.sh
```

Hinweise:
- Redirect-URIs muessen exakt registriert sein (keine Wildcards).
- Bei Host/Port-Aenderung: neu registrieren und neue Client-Credentials setzen.