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)
- P02 Compose is the untouched official ZITADEL
ghcr.io/zitadel/zitadel:v4.20.4, official prebuilt Login V2ghcr.io/zitadel/zitadel-login:v4.20.4, PostgreSQL 17.10 and Traefik 3.7.7. Initial ZITADEL external origin ishttp://localhost:8080. Existingtests/ci/compose.portless.override.yamlremoves the public/shared runner host 8080 mapping and connects through run-ownedzitplane-backend-dev-internalDocker network. Existingbackend_cleanup.shremoves only run-owned project containers/network/volumes with a marker and verifies cleanup. users/ui/src/lib/env.tsrejects an HTTP issuer whenNODE_ENV=production, but accepts HTTP loopback only in development. The Account Portal source must remain unchanged; runningnext devonly 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.users/ui/src/auth.tsuses the genuine NextAuth ZITADEL provider withchecks: [pkce, state, nonce], JWT session, explicit subject and expiration validation and fail-closed no-user identity. Signin UI server action on/signincallssignIn("zitadel", {redirectTo:"/account"});/api/account/mereturns HTTP 401/no-store anonymously and authenticated user ID only for valid session.- Official ZITADEL docs
https://zitadel.com/docs/self-hosting/manage/configure/configureand officialcmd/setup/steps.yamlconfirm FirstInstance machine credentials can create an ephemeral IAM_OWNER service account withZITADEL_FIRSTINSTANCE_PATPATH,ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINE_USERNAME,ZITADEL_FIRSTINSTANCE_ORG_MACHINE_PAT_EXPIRATIONDATE. DO NOT confuse P02's dedicatedIAM_LOGIN_CLIENTPAT with an administrator PAT. CI-only Compose override may add an IAM_OWNER machine PAT to a transient bootstrap volume, only at FIRST startup. - Official project/OIDC application creation:
POST /management/v1/projects;POST /management/v1/projects/{projectId}/apps/oidcwith redirecthttp://localhost:3000/api/auth/callback/zitadel, OIDC Web/Authorization Code/Basic client secret anddevMode:true. Official v2 human APIPOST /v2/users/humancan create a verified disposable user with a random password andchangeRequired: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. - Browser test should use pinned disposable Playwright Chromium, drive real original Login V2
data-testid="username-text-input"anddata-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. - 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:8080issuer,localhost:3000Account 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. - 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
- Implement the CI-only first-instance IAM_OWNER and no-host-port Compose override, root
run.shwith strict run ID/project/network preflight and explicit cleanup scripts; IAM_OWNER PAT expires quickly. - Implement
provision.pywith 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 with0600permissions. Do not dump on API errors. - Implement original-app-only
browser.cjsand ephemeralbrowser.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. - Add new manual-only
.gitea/workflows/p05-oidc-acceptance.ymlwith one isolated job, Docker preflight, no real credentials, always-run cleanup after failure, finite timeout, no CI artifacts containing secrets. - Update
notes/project/docsand exact manifests, inspect allowed-path diff and security integrity, then commit/push Gitea main. - 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.
- 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/mereturns 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.