kiddo/project-management/feedback/oidc-integration-userstories.md

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:

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:

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.