# Wave 10 — Okta OIDC authentication Fresh wave 10. The label was previously used by the LDAPS work under `D13`/`D14`, built on `feat/ldaps-directory-auth`; that branch was deleted rather than merged and never appeared in `IMPLEMENTATION.md`'s wave table, so it carries no claim on the number. See `docs/waves/decisions-2026-09-02.md` (`D15`) for why LDAPS was retired before deployment and Okta chosen instead. Depends only on `main` as it stands after `D15`. Not sequenced behind any other wave. ## Tasks - **T10.1 — Add the Okta OIDC client.** Authlib as a dependency. Config via env vars (`OKTA_ISSUER`, `OKTA_CLIENT_ID`, `OKTA_CLIENT_SECRET`, `OKTA_REDIRECT_URI`), same pattern `AUTH_SECRET_KEY` already uses in `server/auth.py`. - **T10.2 — Login-redirect and callback routes.** A route that sends the browser to Okta's authorize endpoint, and a callback route that exchanges the code for tokens and validates the ID token. Access gating is Okta's job, not this app's: only accounts assigned to the app integration in Okta can reach it at all, so there is no app-side required-group or claim check layered on top. This is a deliberate difference from D13, which had to gate on a required AD group itself because an LDAPS bind alone could not distinguish an assigned user from any other domain account. - **T10.3 — Identity matching and JIT provisioning.** Reuses D13's shape (`_provision_from_directory`-style matching) keyed off an OIDC claim instead of an LDAP search result. **Open dependency:** which claim carries the AD `sAMAccountName` equivalent (`preferred_username`, `upn`, or a custom claim) is asked of security and not yet answered. Build with a configurable claim name and a documented default, not a hardcoded one, so the answer can drop in without a code change. - **T10.4 — Remove the local password path entirely.** Drop `password_hash` (Alembic migration; plain `op.drop_column`, matching existing precedent for other NOT NULL columns on `users` — no `batch_alter_table` needed), remove the bcrypt-based `login()`, remove the username/password form. Real deletion, matching `D15`'s "full replacement," not a toggle or a fallback. Scope corrected by `D16` after hazard review turned up more call sites than the original bullet named: - `create_user()` and `admin_reset_password()` in `server/app.py` (admin console's "add user" and "reset password" routes) — rework to drop the password field entirely rather than break. - `html/users.js`'s "add user" form (`nu-password`) and "Reset password" button — matching frontend change. - `server/manage_users.py` — reworked per `D16` from account *creation* to *promotion*: `create-admin`/`create`/`reset-password` (password-based) are replaced by a promote-by-username command that operates on a row Okta's JIT provisioning (T10.3) already created, never a hand-typed new one. This is now the documented admin-bootstrap path — see `D16`. - `tests/browser_check.py` and `tests/launcher_check.py` — stop calling `auth.hash_password()` to seed fixture rows. - `server/smoketest.py` and `server/seed_demo.py` — currently authenticate via `POST /api/auth/login`. Switch to minting a session with `auth.create_token()` directly, the same technique `browser_check.py` already uses, so both scripts (named explicitly in `CLAUDE.md`'s verification section) keep working without depending on `T10.7`'s timing. - **T10.5 — Frontend: login becomes a redirect, not a form.** `login.html`/`login.js` change to a "Sign in with Okta" flow. Sign-out lands back on the app's own login page. - **T10.6 — Deployment docs and env var reference.** `DEPLOYMENT.md`, `server/.env.example`, `server/README.md` describe the Okta config in place of the LDAP config they never ended up describing (D13 never shipped, so these still describe the original local-password system today). Built: all three rewritten — the five `OKTA_*` vars documented the same way `AUTH_SECRET_KEY` already was, the login-portal/self-service-reset sections replaced with the Okta flow and the promote-not-create admin bootstrap (D16), the smoke-test walkthrough updated for `WP_SMOKE_USER`-only / must-share-`AUTH_SECRET_KEY`-and-DB (T10.4's `smoketest.py` rewrite). Also `docker-compose.yml`, not originally named in this bullet: its `api` service sets `environment:` as an explicit allowlist, not `env_file`, so the documented vars would silently never reach the container without adding them there too — found and fixed in the same commit rather than shipping docs for a config path that doesn't work. `OKTA_IDENTITY_CLAIM` mirrors `okta_auth.py`'s own default (`preferred_username`) in the compose file rather than defaulting to an empty string, which would 503 every sign-in. Logged, not fixed here (out of scope): `users.failed_attempts`/`locked_until` are vestigial (still reset on every Okta sign-in, nothing increments them since local `login()` is gone); `server/README.md`'s own "Production — Docker Compose" section is a self-contained alternate quickstart that already diverged from the real root `docker-compose.yml` before this task and still does. - **T10.7 — Test coverage without a live Okta dependency.** A fake-OIDC-provider test seam, mirroring `ldap_fake.py`, so the suite runs with no live Okta tenant reachable. Built: `server/okta_fake.py` (env-driven, `WP_OKTA_FAKE_DIRECTORY`, production-refusing the same way `ldap_fake.py` does), dispatched from `okta_auth._build_oauth()` before the real Authlib client is considered. Only the two Authlib calls that touch the network — `authorize_redirect` / `authorize_access_token` — are faked; `app.py`'s `okta_login()`/`okta_callback()` (the `?next=` guard, the disabled-account check, JIT provisioning, the identity-claim lookup) run unmodified against the fake, same boundary the LDAP predecessor drew around the anonymous-bind guard. Two fake-only routes (`/_fake_provider`, `/_fake_provider/consent`) stand in for Okta's own sign-in screen and are registered in `app.py` only when the fake is active at import time — in production they do not exist, not merely refuse. `tests/browser_check.py`'s `start_server()` now takes an optional `extra_env` and sets `WP_OKTA_FAKE_DIRECTORY` unconditionally (same reasoning `ldap_fake`'s equivalent used: almost nothing signs in, but the one check that does should not fail mysteriously). `tests/url_state_check.py` scenario 2 is un-skipped and drives the real round trip — login.html's button, the fake picker page, the fake consent redirect, `okta_callback()` — proving `?next=` survives it, same tightened "actually left login.html" assertion the LDAP predecessor's own bug fix used. `tests/okta_auth_check.py` is new: the production guard, single-use/replay on the authorization code, an unsolicited callback hit, a tampered state, a denied consent, an unknown identity, a disabled account, JIT provisioning, an existing admin surviving unchanged, same-site vs. off-site `?next=`, and `OKTA_IDENTITY_CLAIM` genuinely working under a non-default claim name — 22/22. The dev sandbox this was built in has no headless browser and no way to install one, so `tests/url_state_check.py` and `tests/browser_check.py` (both need `tests/cdp.py`'s real headless Chromium) could not be run there — only `okta_auth_check.py`'s HTTP-level coverage of the same mechanism. Run for real afterward on a machine with Docker, via a separate general-purpose tool (`headless-py-test-runner`, kept out of this repo — it is not Work Package Suite specific): `url_state_check.py` 26/26, including scenario 2's real click-through of the fake-Okta round trip, and `browser_check.py` 71/71. Gap closed. **Validated 2026-09-03:** `tests/okta_auth_check.py` 22/22 (no browser needed) · `tests/url_state_check.py` 26/26 · `tests/browser_check.py` 71/71 — all three run clean, the last two against real headless Chromium via Docker. - **T10.8 — Verification.** 390px and 1440px, full suite, done-when checks per task, matching the rigor D13 was held to. - **T10.9 — Rollback-aware deploy runbook.** Raised after hazard review found `DEPLOY-runbook-2026-08-04.md`'s Rollback section has no case for a migration whose `downgrade()` cannot restore the data it drops — see `D17`. `T10.4`'s `1d60a608bb51_drop_local_password` is exactly that: the schema comes back, the bcrypt hashes do not. Built: `DEPLOY-runbook-2026-09-03.md`, following the 2026-08-04 runbook's structure (fill-in table, numbered deploy steps, case-by-case Rollback section, Notes). Names the five `OKTA_*` vars as newly required (the precedent's "no new environment variables" note does not carry over), treats the pre-deploy backup as the only way back once the migration commits, and splits Rollback into the fixable case (Okta app integration misconfigured — fix and redeploy `api`, no data at risk, migration stays applied) versus the severe case (abandoning Okta for local-password code — only the destructive backup restore gets there, reusing the 2026-08-04 runbook's own Case C procedure). D16's no-break-glass posture is stated plainly rather than left implicit. Logged, not fixed here (out of scope): `okta_auth.describe()`'s startup log line (referenced by `DEPLOYMENT.md`/`server/README.md`) has no caller anywhere in `server/app.py` — nothing actually prints it at process start. The runbook's Step 4 therefore verifies via a live Okta sign-in rather than a log line, and this gap is flagged in `docs/waves/backlog.md` as a candidate fix (wiring `describe()` into startup) since it directly bears on deploy verifiability. `DEPLOY-login-portal.md` is now fully stale (bcrypt, `create-admin --password`, none of which still exist) — not touched, no task claims it. ## Still open - The OIDC claim mapping (`T10.3`). - Final confirmation of the redirect/callback URI (`https://wp.controls.dev/api/auth/okta/callback` proposed, pending security). - The `Business Technology Group` pilot assignment in Okta. Closed since first written: admin bootstrap and break-glass posture, previously open questions, decided in `D16` (2026-09-03) and folded into `T10.4` above.