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

12 KiB

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

Date: 2026-11-22 User-approved baseline: f423c696544f28a42d6a5d1ad0acfd88a3b6f56d on Gitea vibtools/ZitPlane/main. Phase status: IMPLEMENTED IN SOURCE / ONE GITEA RUN #90 COMPLETED FAILURE. Real OIDC client/user/browser acceptance BLOCKED by private localhost:8080 forwarder readiness. Mandatory cleanup PASS. This plan was written before source 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.

One focused Gitea CI cycle — actual terminal result, 2026-11-22

Single authorized run: Gitea Run #90, job #197, tested source SHA cbcd60e76ec909df4f9c5826adf7a3e2a899c73e. workflow_dispatch on main. Created 2026-11-22 17:17:37 UTC; terminal 17:20:07 UTC. Overall status completed, conclusion FAILURE. No second CI run. Last commit after this run, if present, contains only result documentation, not a new verified source candidate.

Job step Result Source-backed exact evidence
Install Git before checkout and actions/checkout@v4 PASS Gitea job #197 steps #0/#1 both success
Docker daemon + numeric run-owned preflight PASS ZITPLANE_OIDC_DOCKER_PREFLIGHT_PASS
Portless Compose/CI IAM_OWNER configuration PASS ZITPLANE_OIDC_NO_PUBLISHED_PORT_AND_OWNER_CONFIG_PASS; no runner host port
Disposable PostgreSQL, ZITADEL API, official Login V2 and Traefik health PASS Four containers healthy, ZITPLANE_OIDC_FOUR_SERVICES_READY_PASS
CI-only private namespace localhost:8080 loopback forwarder readiness FAIL / BLOCKER ZITPLANE_OIDC_PROVISION_BLOCKED: Disposable localhost issuer port forwarding was not ready (~17:19:54 UTC)
Real OIDC project/client/user API provisioning NOT EXECUTED provision.py::wait_until_ready() timed out first, before any API create request
Real Chromium/Login V2/PKCE/state/nonce/authorization-code/Account session/negative browser checks NOT EXECUTED No project, client or human created; browser never started
always() owned Docker cleanup job step #3 PASS ZITPLANE_BACKEND_CLEANUP_VERIFIED_PASS; ZITPLANE_OIDC_ALL_RESOURCES_CLEANED_PASS (~17:19:59 UTC); job cleanup step final success

Exact blocker, boundaries and remediation candidate

The CI code used a run-owned detached alpine:3.21 sidecar sharing the proxy container network namespace and attempted apk add --no-cache socat (stdout/stderr suppressed) before starting a loopback listener from 127.0.0.1:8080 to proxy:80. The helper saw no working local endpoint within its bounded 70-second readiness poll. The actual root cause is not yet proven: the sidecar might have exited (e.g. package installation) or its listener/Traefik forwarding/Host routing could have failed. Because the sidecar's installation output was suppressed, there is no diagnostic evidence proving which one. This cannot be attributed to Auth.js, PKCE, user credentials or OIDC endpoints; none was exercised.

Proposed P05-OIDC-02: explicitly approve narrow CI-only tests/ci/oidc_e2e/run.sh, provision.py and, only if necessary, cleanup.sh changes to diagnose the run-owned sidecar's actual exit/running/listening state, prefer an immutable/pinned prebuilt socat image rather than first-installing a package after container start, verify local loopback readiness and exact issuer/Host routing before provisioning. Keep no host port, no leaked credentials or sensitive URLs, unchanged app/backend/Compose/PNPM source, and owned-only cleanup. Perform a new separately approved single Gitea cycle to test genuine provisioning and browser login; do not bypass authentication to satisfy it.

Phase closure

P05-OIDC-01 CI harness source IMPLEMENTED; interactive OIDC acceptance BLOCKED on isolated network forwarding. Safe CI-owned cleanup VERIFIED, no resources left from run #90. All positive authenticated user/client/browser tests UNVERIFIED; MFA/passkey and production HTTPS/Console remain outside scope. Zero local app installs/builds/tests, no real identities/production deployment or source edits after Run #90. Unrelated untracked AI_INSTRUCTIONS.md untouched.