70 lines
12 KiB
Markdown
70 lines
12 KiB
Markdown
# 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](https://dev.ivib.cc/vibtools/ZitPlane/actions/runs/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.
|