Files
ZitPlane/notes/P05-OIDC-01.md
T

8.5 KiB

P05-OIDC-01 — Real Disposable OIDC Login and Session Acceptance

Date: 2026-11-22 User-approved baseline: f423c696544f28a42d6a5d1ad0acfd88a3b6f56d on Gitea vibtools/ZitPlane/main. Pre-implementation state: APPROVED / SCOPE LOCKED — this planning record is written before any CI implementation edits. Prior verified evidence: Run #86 disposable backend/JWKS/DB persistence/teardown PASS; Run #87 Account build/security and negative authorization PASS; Run #89 Login V2 frozen standalone build/1219 tests and zero Moderate+ audit PASS. None proved a real authorization callback with a human user.

Exact approved write scope and hard boundaries

Allowed: new .gitea/workflows/p05-oidc-acceptance.yml, new tests/ci/oidc_e2e/**, narrow CI-only helper files under tests/ci/**, notes/**, project/**, relevant docs/**, associated README.md and exact MINIFEST.md updates and root navigation only if necessary.

Read-only: core/backend/zitadel/**, deployment/docker/**, auth/ui/v2/** application/authentication code, users/ui/** application/authentication code, all package manifests and lockfiles, production infrastructure, third-party upstream source, secrets, and all unrelated files. Preserve unrelated untracked root AI_INSTRUCTIONS.md without staging.

No local application installs/builds/tests/dev servers/Docker. No production deployment, real credentials/accounts, tags or releases. One focused Gitea Actions CI cycle ONLY. A blocked test is documented honestly, not called PASS.

Verified source and official API research (read-only, before implementation)

  1. P02 Compose is the untouched official ZITADEL ghcr.io/zitadel/zitadel:v4.20.4, official prebuilt Login V2 ghcr.io/zitadel/zitadel-login:v4.20.4, PostgreSQL 17.10 and Traefik 3.7.7. Initial ZITADEL external origin is http://localhost:8080. Existing tests/ci/compose.portless.override.yaml removes the public/shared runner host 8080 mapping and connects through run-owned zitplane-backend-dev-internal Docker network. Existing backend_cleanup.sh removes only run-owned project containers/network/volumes with a marker and verifies cleanup.
  2. users/ui/src/lib/env.ts rejects an HTTP issuer when NODE_ENV=production, but accepts HTTP loopback only in development. The Account Portal source must remain unchanged; running next dev only inside a disposable Gitea Docker container is necessary for the current HTTP localhost issuer. This can prove the real application Auth.js OIDC flow in CI development context, NOT production-HTTPS topology. For production-style TLS additional approval is required.
  3. users/ui/src/auth.ts uses the genuine NextAuth ZITADEL provider with checks: [pkce, state, nonce], JWT session, explicit subject and expiration validation and fail-closed no-user identity. Signin UI server action on /signin calls signIn("zitadel", {redirectTo:"/account"}); /api/account/me returns HTTP 401/no-store anonymously and authenticated user ID only for valid session.
  4. Official ZITADEL docs https://zitadel.com/docs/self-hosting/manage/configure/configure and official cmd/setup/steps.yaml confirm FirstInstance machine credentials can create an ephemeral IAM_OWNER service account with ZITADEL_FIRSTINSTANCE_PATPATH, ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINE_USERNAME, ZITADEL_FIRSTINSTANCE_ORG_MACHINE_PAT_EXPIRATIONDATE. DO NOT confuse P02's dedicated IAM_LOGIN_CLIENT PAT with an administrator PAT. CI-only Compose override may add an IAM_OWNER machine PAT to a transient bootstrap volume, only at FIRST startup.
  5. Official project/OIDC application creation: POST /management/v1/projects; POST /management/v1/projects/{projectId}/apps/oidc with redirect http://localhost:3000/api/auth/callback/zitadel, OIDC Web/Authorization Code/Basic client secret and devMode:true. Official v2 human API POST /v2/users/human can create a verified disposable user with a random password and changeRequired:false. Cite official refs: https://zitadel.com/docs/reference/api/management/zitadel.management.v1.ManagementService.AddOIDCApp, https://zitadel.com/docs/guides/integrate/login-ui/username-password. API permissions/response must be checked by the actual isolated runtime; do not invent client/user IDs.
  6. Browser test should use pinned disposable Playwright Chromium, drive real original Login V2 data-testid="username-text-input" and data-testid="password-text-input"; no mocked identity provider, fake token, cookie injection, insecure TLS bypass or authentication shortcut. Test real browser state/PKCE/nonce, actual token exchange, callback, protected user identity positive, anonymous/invalid-flow negative and local sign-out if feasible.
  7. CI network design: avoid publishing any host port. Launch P02 services with run-owned Compose project + portless override and an additional CI-only first-instance owner PAT override. Run a transient loopback port-8080 TCP forwarder in the isolated Traefik proxy network namespace, so localhost:8080 issuer, localhost:3000 Account Portal and real browser all share one disposable network namespace without host binds. Start a pinned Playwright image as a runner container sharing that namespace; copy only Account app and CI scripts, install project dependencies and Playwright only in ephemeral runner; no local Windows builds/tests. API provisioning uses separate Python runtime with IAM_OWNER PAT volume read-only and writes disposable client/user secrets only to a CI-owned volume, which is shared read-only with the browser runner. Never print or upload PAT, passwords, client secret, session tokens, screenshots or callback query values.
  8. Fail-closed preflight and cleanup: refuse preexisting CI project, existing fixed network, unrelated credentials/markers/volumes; cleanup owns only exact run ID and project marker. Always remove owned Playwright and TCP forwarder containers, verify no leftover CI owned app browser containers/secret volume, call existing backend cleanup for ZITADEL stack, and fail job if cleanup incomplete. No production/user volumes or network touched.

Focused implementation plan, in order

  1. Implement the CI-only first-instance IAM_OWNER and no-host-port Compose override, root run.sh with strict run ID/project/network preflight and explicit cleanup scripts; IAM_OWNER PAT expires quickly.
  2. Implement provision.py with bounded official management/user API calls, exact expected project/app/client/human response checks and no secret logs. Save generated secrets only inside disposable volume with 0600 permissions. Do not dump on API errors.
  3. Implement original-app-only browser.cjs and ephemeral browser.sh: invoke real Next dev (CI ONLY) and real Playwright Chromium for positive OIDC browser flow, PKCE/state/nonce observation, account API/session positive and negative, bounded wait and safe error diagnostics. No mock session or bypass.
  4. Add new manual-only .gitea/workflows/p05-oidc-acceptance.yml with one isolated job, Docker preflight, no real credentials, always-run cleanup after failure, finite timeout, no CI artifacts containing secrets.
  5. Update notes/project/docs and exact manifests, inspect allowed-path diff and security integrity, then commit/push Gitea main.
  6. Dispatch ONE focused isolated Gitea run; check exact actual steps/jobs/cleanup. Record complete PASS only on real positive browser login and proper teardown. If provisioning/browser/network can't complete, record the exact blocker and remaining P05-OIDC acceptance as BLOCKED/DEFERRED, without a second run or auth/source modification. Final notes/docs commit and remote SHA verify.
  7. Automatically propose next narrow Scope Lock + compact plan and copy-ready approval, scoped to actual remaining blocker if any.

Acceptance gates (all mandatory, NOT claimed in advance)

  • Disposable ownership/pinned images/boot/readiness/client project and real test human creation PASS, with no real secrets used.
  • Browser reaches original Login V2 via real ZITADEL authorize redirect with PKCE S256, state and nonce; real password verifies and callback exchanges code.
  • GET /api/account/me returns actual newly created user ID with private/no-store; protected Account page accessible with session, anonymous denied; malicious callback/session/issuer state rejected.
  • Always-run owned container/volume/network/credential cleanup verified.
  • No unauthorized repo changes, local builds/tests, fake PASS or production deployment. MFA/passkeys and production TLS out of scope unless actually verified with real flows; must remain deferred.