Files
ZitPlane/project/OIDC-E2E-ARCHITECTURE.md
T

7.2 KiB

P05-OIDC-01 — Disposable Real Browser Authentication Architecture

Approved baseline: f423c696544f28a42d6a5d1ad0acfd88a3b6f56d. Current status: CI-only source implemented; real user callback/session acceptance requires actual terminal Gitea evidence.

Source and trust boundaries

Exact first-party file Main function / why it exists
.gitea/workflows/p05-oidc-acceptance.yml Only manual Gitea Docker job, installs Git before checkout, executes CI-only harness and always calls owned-only teardown; never auto-runs on untrusted PRs
tests/ci/oidc_e2e/run.sh Numeric Gitea run-ID validation, refusal of existing fixed network/projects/volumes/.env, disposable P02 Compose startup with no host ports, CI-only loopback namespace and secret volume, invokes official API provisioning and Chromium test
tests/ci/oidc_e2e/compose.owner.override.yaml Add first-instance ephemeral IAM_OWNER machine PAT only to the CI-owned API service; official P02 developer Compose unchanged
tests/ci/oidc_e2e/provision.py request() restricted to localhost API + Host, validates issuer/discovery, creates real project/Account OIDC Web client and verified temporary human via official management/User v2 APIs, writes generated credentials to 0600 separate CI secret volume, suppresses secret/error-body logging
tests/ci/oidc_e2e/browser.sh Disposable Playwright Chromium image installs committed Account npm dependencies and pinned Playwright v1.58.2 inside container, not local developer PC
tests/ci/oidc_e2e/browser.cjs main() drives actual browser OIDC authorization, original Login V2 UI fields, Auth.js callback, authenticated ID/API/pages, anon/invalid callback negative checks and local session sign-out; no mock or injected sessions
tests/ci/oidc_e2e/cleanup.sh Only owner-labeled browser/forwarder containers and secret volume are removed, then existing backend_cleanup.sh removes and verifies run-marked Compose/DB/bootstrap state; fail-closed on unverified cleanup
tests/ci/oidc_e2e/{README.md,MINIFEST.md} Isolated harness guide, exact source ownership and constraints

Exact runtime topology

The P02 backend routes ZITADEL at http://localhost:8080 and prebuilt official Login V2 at /ui/v2/login. The pre-existing CI compose.portless.override.yaml removes the developer's host loopback bind. This phase uses an isolated Docker proxy network namespace, with a run-owned TCP forward from namespace-local localhost:8080 to Traefik:80. Both the one-off provisioning container and the Chromium/Account runner share that private namespace; nothing listens on the Gitea host's port 8080 or 3000.

users/ui/src/lib/env.ts disallows HTTP issuer in production and permits only HTTP localhost when NODE_ENV=development. Running the unmodified Account Portal with next dev inside a disposable CI container is therefore intentionally a development-origin functional acceptance, not a claim of HTTPS/production security acceptance. users/ui/src/auth.ts has real NextAuth ZITADEL checks: ["pkce","state","nonce"], nonempty subject and token expiry guards; this phase does not edit them.

Identity/provisioning security

A first-instance IAM_OWNER service user is created only inside disposable ZITADEL during initial setup, with its PAT written to the run-owned bootstrap volume and a short expiry. This is not the existing IAM_LOGIN_CLIENT service token used by the official Login V2. The IAM_OWNER token is mounted read-only only to the provisioning Python container, not to Chromium. The test app/client secret and randomly generated password are transferred via a separate run-labeled volume read-only to Chromium, and neither logs nor Git contain sensitive values. The test user's email is a verified .invalid address, not a real recipient; owner token, identity client and user are destroyed along with owned Postgres/bootstrap volumes.

Verification contract

  • ZITADEL 4 services live, exact isolated portless config, authoritative issuer and OIDC discovery
  • IAM_OWNER PAT exists, official project/app/client/user APIs return valid required fields
  • Chromium's real authorization navigation contains response_type code, matching client/redirect, S256 challenge, state and nonce
  • Original Login V2 form receives the ephemeral username/password; browser follows a genuine authorization code exchange to the protected Account Portal
  • Actual GET /api/account/me returns created subject ID and no-store, HttpOnly session cookie; protected page valid
  • Anonymous API + protected page rejected; tampered callback fails closed; portal sign-out returns unauthenticated API
  • Always owned-only cleanup confirms browser, port forwarder, secret volume, Compose containers, network, DB and bootstrap credentials gone

Never equate a static source check, issuer/JWKS check or successful redirect with a successful interactive login/callback. MFA/passkey, Admin Console human sign-in, production TLS and custom source-built Login V2 runtime wiring are future explicitly approved phases.

References

ZITADEL official endpoints and bootstrap specification: https://github.com/zitadel/zitadel/blob/main/cmd/setup/steps.yaml, https://zitadel.com/docs/reference/api/management/zitadel.management.v1.ManagementService.AddOIDCApp and https://zitadel.com/docs/guides/integrate/login-ui/username-password. Actual Gitea result: notes/P05-OIDC-01.md.

Run #90 terminal evidence and network integration blocker

Gitea manual Run #90, tested cbcd60e76ec909df4f9c5826adf7a3e2a899c73e, FAILED, job #197. run.sh correctly validated runner Docker/ownership, portless Compose with disposable first-instance IAM_OWNER configuration and brought all four P02 services up healthy. It created a private alpine:3.21 namespace-sharing TCP forwarder; that helper attempted to install socat with its installation output silenced. The following provision.py::wait_until_ready() could not reach the expected private localhost:8080 after 70 seconds and raised ZITPLANE_OIDC_PROVISION_BLOCKED. The reason the forwarder was not ready remains unproven (container exit, package install, socket bind or reverse-proxy routing cannot be distinguished from the available log). Do not misattribute failure to ZITADEL client provisioning or browser authentication: both were NOT EXECUTED.

The mandatory cleanup.sh step #3 succeeded and printed ZITPLANE_BACKEND_CLEANUP_VERIFIED_PASS + ZITPLANE_OIDC_ALL_RESOURCES_CLEANED_PASS. It removed only run #90-owned proxy namespace forwarder, separate ephemeral secrets volume, Compose containers, Postgres/bootstrap volumes and fixed CI network. Backend bootstrap/cleanup PASS; full end-to-end OIDC acceptance BLOCKED.

Next P05-OIDC-02 should narrowly instrument/check forwarder startup before provisioning, use an approved pinned prebuilt image to avoid silent runtime package installation, verify exact private loopback listener/Host routing without any host port exposure, preserve original Go backend/Compose/Login/Auth.js and credentials isolation, then run one separately authorized Gitea acceptance cycle. No CI-only patch in P05-OIDC-01 was executed after Run #90.