# Wave 13 — Okta/AD deprovisioning sync **Items:** `D18` **Depends on:** wave 10 merged (it is). Not blocked by wave 11 or wave 12, but shares `server/app.py` account-state surface with wave 12 (`CR-020`) — sequence commits to avoid an avoidable conflict. **Decision record:** `docs/waves/decisions-2026-09-17.md` Six tasks, in build order. **T13.3's fail-closed behavior is the most important done-when list in this wave — do not relax it to ship faster.** --- ### T13.1 — D18: idle timeout with an absolute ceiling - **Items:** `D18` - **Depends on:** nothing (first task, independent of the rest) - **Blocks:** nothing - **Surface:** `server/` - **Files:** `server/auth.py`, `server/app.py` (`auth_gate` middleware), `server/.env.example`, `DEPLOYMENT.md` **Revised 2026-09-23** — originally just "shrink `AUTH_SESSION_HOURS`". Matt asked whether an idle timeout would be a better fit than a flat session length. It is, but not by itself — see the decision record's reasoning on why idle-with-no-ceiling is actually a worse fit for this item's own threat model than a flat expiry would have been. Build both. **Do:** - Add `login_at` to the JWT payload in `create_token()` — the original sign-in time, distinct from `iat`, which becomes "when THIS token was issued" once tokens start getting reissued. `login_at` never changes across reissues; it's what the absolute ceiling is measured from. - Add `AUTH_IDLE_MINUTES` (default 30). `AUTH_SESSION_HOURS` stays the name for the absolute ceiling, default changing from 12 to a proposed 8 — update its docstring/comment in `auth.py` and `.env.example`, since its MEANING is changing (session length -> hard ceiling on top of a sliding idle window), not just its value. - In `auth_gate` (`server/app.py`), after confirming a request is authenticated: if `now < login_at + AUTH_SESSION_HOURS` (the ceiling hasn't passed), compute `new_exp = min(now + AUTH_IDLE_MINUTES, login_at + AUTH_SESSION_HOURS)`. If `new_exp` is meaningfully later than the current token's `exp` (throttle this — do not reissue on every single request, only when enough time has passed to be worth a new cookie; a few minutes of slack is fine), mint a refreshed token carrying forward `sub`/`username`/ `role`/`ver`/`login_at` unchanged, and set it on the response. - If the ceiling HAS passed, do not refresh — let the existing token expire on its own terms (it may already be invalid, or may tick over within the idle window; either way, no new one is issued past the ceiling). - The middleware should not need a DB round trip to do this — everything needed (`sub`, `username`, `role`, `ver`, `login_at`) is already in the validated claims. `get_current_user`'s existing per-request `is_active`/ `token_version` check is unaffected and still runs separately. **Do not:** reissue the cookie on every request unconditionally — that's a `Set-Cookie` header on every API call for no benefit over a coarser refresh. Do not let the ceiling check silently vanish for tokens issued before this change ships — a token with no `login_at` claim should fall back to treating its own `iat` as `login_at`, not bypass the ceiling entirely. **Done when:** - [x] a session with continuous activity stays alive past 30 minutes but is cut off at the `AUTH_SESSION_HOURS` ceiling regardless *(2026-10-16, T13.6: a request every minute for 10 hours: alive well past 30 minutes, never extended past login + 8 h, cut off at the ceiling, original `login_at` kept.)* - [x] a session with no activity for 30+ minutes is rejected on its next request *(2026-10-16, T13.6: an idle token gets 401 on a gated route; one inside the window gets 200.)* - [x] the cookie is not rewritten on every single request — verify the refresh is throttled, not unconditional *(2026-10-16, T13.6: 20 rapid requests on a fresh session: 0 rewrites; 480 requests over 8 h: about one rewrite per 10 minutes; a refreshed cookie is not rewritten again on the next request. Mutation test: removing the throttle fails 3 checks.)* - [x] a pre-existing token with no `login_at` claim (simulating a session issued before this shipped) still gets a hard ceiling, via the `iat` fallback *(2026-10-16, T13.6: a token with iat 9 h ago and a still-valid old exp is not extended; one with iat 1 h ago is refreshed with `login_at` taken from `iat`; no `login_at` and no `iat` is not refreshed and does not crash. Mutation test: giving it a fresh ceiling fails.)* - [x] `.env.example` and `DEPLOYMENT.md` explain both variables and flag both defaults as proposed, not confirmed against Okta's own session policy *(2026-10-16, T13.6: both variables are in both files, and both call the defaults proposed.)* - [x] existing session/auth tests updated for the new mechanism, not just a new number *(2026-10-16, T13.6: there were none. T13.1 shipped with no test of its own. `tests/session_idle_check.py` is that test (T13.6 added it).)* --- **Found while writing that test (T13.6, 2026-10-16):** - Nothing under `/api/auth/` slides the session. `auth._EXEMPT_PREFIXES` covers that whole prefix, so `auth_gate` never refreshes there (including `/api/auth/me`). A page that only called `/api/auth/me` would not extend its session. The spec says "after confirming a request is authenticated", and these routes are not confirmed by the gate, so this is as written. Noted, not changed. - The wave's exit criteria below say `AUTH_SESSION_HOURS` defaults to **2**. T13.1 (this section), `auth.py`, `.env.example` and `DEPLOYMENT.md` all say **8**. The code and the T13.1 text agree, so the exit line looks like a leftover from before the 2026-09-23 revision. Not changed here: it is a product number. Needs Matt to say which one he means. ### T13.2 — D18: Okta Management API client - **Items:** `D18` - **Depends on:** nothing (independent of T13.1) - **Blocks:** T13.3 - **Surface:** `server/` - **Files:** new `server/okta_sync.py` (or extend `server/okta_auth.py` — task's call), `server/.env.example` **Do:** A small client for Okta's user-list endpoint, authenticated with a new, separate credential (e.g. `OKTA_API_TOKEN`) — not the OIDC client secret used for sign-in. Fetch the full user list (paginated per Okta's API) rather than one-by-one lookups per local user; this app has ~20-odd accounts today, and a list-and-diff is simpler and cheaper than N calls. Return each Okta user's identity-claim value (matching `OKTA_IDENTITY_CLAIM`, already confirmed live per wave 10) and status. Follow the existing pattern for external credentials in this repo (`MICRON_DB_URL`, `SMTP_PASSWORD`): env-only, never logged, never returned to the browser in an error message. **Do not:** reuse `OKTA_CLIENT_ID`/`OKTA_CLIENT_SECRET` for this. Sign-in and the management API are different trust boundaries with different scopes; conflating them means a compromise or rotation of one affects the other unnecessarily. **Done when:** - [x] the client authenticates with its own credential, distinct from the OIDC client *(2026-10-16: `OKTA_API_TOKEN`, sent as `Authorization: SSWS`. `tests/okta_sync_check.py` sets a different OIDC client secret and asserts it is never sent.)* - [x] it fetches the complete Okta user list, handling pagination *(2026-10-16: follows `Link: rel="next"`, 200 per page, 2-page case checked. A next link to another host is refused, a chain longer than 50 pages raises instead of cutting the list off, redirects are never followed.)* - [x] an auth failure or malformed response raises a clear, specific error rather than returning an empty list indistinguishable from "everyone was deprovisioned" — this distinction is what T13.3 depends on *(2026-10-16: `OktaSyncError` for HTTP 401/403/404/429/5xx, redirects, network errors, timeouts, non-JSON, non-list, a bad item (never skipped), and an empty list. 31 failure checks. Mutation test: making the client return `[]` on an error fails 10 of them.)* - [x] the credential is never logged or surfaced in any API response *(2026-10-16: error messages carry the class name and HTTP status only, never the URL or a header. `describe()` has no token. Nothing is wired to an API response yet; T13.4 wires the startup log.)* --- ### T13.3 — D18: the sync job - **Items:** `D18` - **Depends on:** T13.2 - **Blocks:** T13.4 - **Surface:** `server/` - **Files:** `server/okta_sync.py`, `server/app.py` (or wherever `log_event` lives) **Do:** Compare the Okta user list (T13.2) against local `users` rows. For any local `is_active=True` user whose Okta identity is missing from the list, or present with a non-active status, set `is_active=False` and write an `AuditLog` row (`actor="system:okta_sync"`, action e.g. `user_deprovisioned_by_sync`, detail naming the Okta status found). Never touch a user already `is_active=False`. Never re-enable anyone. **The fail-closed rule, non-negotiable:** if T13.2's client raises an error of any kind (network, auth, malformed response, timeout), this task takes **no action on any account** for that run and logs the failure clearly (server log, at minimum). An error is never treated as "Okta returned zero active users." Write a test that asserts this directly: feed the sync a failing client and assert zero rows changed and zero `AuditLog` entries written. **Done when:** - [x] a user missing from Okta's list, or present but not active, is disabled with a correctly-detailed audit row *(2026-10-16: see "Decided 2026-10-16" below for which statuses count as "not active". Audit row: actor `system:okta_sync`, action `user_deprovisioned_by_sync`, `entity_type` user, `detail` `{okta_status, via}`; a missing user is recorded as `MISSING`.)* - [x] a user already disabled is left alone (no duplicate audit row each run) *(2026-10-16: a second run over the same data writes no new rows.)* - [x] an active Okta user already active locally produces no audit row (only changes are logged, not a clean bill of health every cycle) *(2026-10-16: verified in `tests/okta_sync_job_check.py`.)* - [x] **a simulated Okta API failure results in zero account changes and zero audit rows** — this is the one check that must never be skipped or weakened *(2026-10-16: 10 stand-in failures (OktaSyncError, RuntimeError, ConnectionError, TimeoutError, ValueError, KeyError, empty list, None, two kinds of garbage), 4 through the real client (HTTP 401/403/429/500), the default path with no token, a failed commit, and a wrong identity attribute. Each: `ok` is False, zero accounts changed, zero audit rows. Mutation test: removing the fail-closed branch and the zero-match guard fails 28 of these.)* - [x] the job never re-enables an account under any input *(2026-10-16: a disabled account that is ACTIVE in Okta stays disabled, and `okta_sync.py` contains no assignment of `is_active` to True.)* --- **Decided 2026-10-16 (Matt, in chat):** which Okta statuses disable an account. The spec says "a non-active status". Read literally, that also catches `PASSWORD_EXPIRED`, `LOCKED_OUT` and `RECOVERY`, which people leave on their own, and this job never re-enables, so one AD password expiry would lock someone out of the app until an admin stepped in. Decided: an account disables when it is **missing** from Okta's list, or every Okta entry for it is **SUSPENDED** or **DEPROVISIONED** (`DISABLING_STATUSES` in `server/okta_sync.py`). Okta's default user list already leaves out DEPROVISIONED users, so those arrive as "missing". **Added 2026-10-16, inside decision 4's "anything the sync can't confidently parse":** if there are active local accounts and **none** of them matches any Okta user, the run is refused and nothing changes. That pattern means the identity attribute is wrong (`OKTA_SYNC_PROFILE_ATTRIBUTE`), not that the whole company left. It is a guard, not a new feature. Raise it in the PR. **Open, for the PR / Nick:** which Okta profile attribute equals the `preferred_username` claim in this tenant. The client assumes `profile.login`, Okta's default. Confirm before the first live run. A wrong value is caught by the zero-match guard above only when it matches nobody at all; a value that matches some accounts and not others would disable the rest. See `BL-069`. ### T13.4 — D18: run it on a schedule - **Items:** `D18` - **Depends on:** T13.3 - **Blocks:** T13.6 - **Surface:** `server/`, `docker-compose.yml` - **Files:** `server/app.py` (startup hook) or a new sidecar per the `backup` container's pattern — task's call, per the decision record's noted alternative **Do:** Wire T13.3 to run on an interval (proposed 15 minutes, env-overridable — e.g. `OKTA_SYNC_INTERVAL_SECONDS`, matching `BACKUP_INTERVAL_SECONDS`'s naming). Default choice is an in-process background task in the `api` container; if a separate container is chosen instead, follow the `backup` service's shape (own Dockerfile or script, `internal` network plus whatever egress reaching Okta requires — check whether `outbound` as currently defined is sufficient or Okta needs a distinct allowance). **Done when:** - [x] the job runs automatically on the configured interval without manual invocation *(2026-10-16: a daemon timer thread starts from the app's lifespan hook (`server/app.py`), checks once a minute, and ran the sync on its own in `tests/okta_sync_schedule_check.py`. With `OKTA_API_TOKEN` unset it starts nothing and the startup log says `Okta sync DISABLED`. Booted the real app both ways; the thread starts and ends with the app.)* - [x] interval is env-configurable with a sane default *(2026-10-16: `OKTA_SYNC_INTERVAL_SECONDS`, default 900. A non-number uses the default. A value under 300 is raised to 300. Passed through `docker-compose.yml`.)* - [x] a container restart does not produce a duplicate/overlapping run, and a slow cycle does not stack with the next one *(2026-10-16: the api runs 2 gunicorn workers, so each starts its own timer. One row in `app_settings` (key `okta_sync`) is the gate: a worker claims a cycle with one atomic conditional UPDATE, so exactly one wins. Checked with 8 racing workers on a file database, 15 rounds plus the first-insert race: exactly 1 winner every time. The row outlives a restart, so a restart inside the interval starts nothing. A slow run cannot overlap the next: a fetch is capped at 120 s in total and the interval cannot go below 300 s. Inside one process the thread runs one cycle at a time. This needed no migration: `app_settings` already exists.)* --- **Decided 2026-10-16 (task's call, per this task's "Do"):** in-process timer in the `api` container, as D18 proposed, not a sidecar. The `backup` pattern was the alternative; it would need its own image and would not remove the 2-worker duplicate question, because the sync reads the application database anyway. **Network check, as the task asked:** the `outbound` network the `api` service already joins is an ordinary bridge with a gateway, so Okta is reachable with no network change. The host firewall must allow https to the Okta org. **One change to T13.2's code:** `fetch_users()` now also stops after 120 seconds in total (`TOTAL_DEADLINE_SECONDS`), which is what lets the scheduler promise no overlap. Tested in `tests/okta_sync_check.py` section 8. **T13.4 follow-up, 2026-10-16:** the sync's INFO log lines did not appear in `docker compose logs api`. Nothing in the app configures Python logging, and gunicorn configures only its own loggers, so INFO from any `wpsuite.*` logger is dropped. The T13.4 check booted the app in-process with logging switched on, which hid it. With the exact Dockerfile launch (2 gunicorn workers), a healthy start printed zero Okta lines. `okta_sync.py` now gives its own logger one stderr handler (only when the root logger has none). Re-run with the real gunicorn command: `configured` and `scheduled` (or `DISABLED`) now print once per worker. No other module's output changed. App-wide logging stays a separate question (BL-028 is the same family). ### T13.5 — D18: admin visibility - **Items:** `D18` - **Depends on:** T13.3 - **Blocks:** T13.6 - **Surface:** `html/` - **Files:** `html/users.js` / `html/admin.js` (wherever audit history is already surfaced) **Do:** Confirm an auto-disable reads clearly wherever admins already look at account history — the actor string (`system:okta_sync`) should be self-explanatory in context, not require reading server logs to understand. Do not build new UI beyond making sure the existing audit surface renders this actor sensibly. Email/notification to admins on auto-disable is a noted fast-follow (the decision record flags it as open, not required here) — do not build it in this task; log it instead if it's tempting to add. **Done when:** - [x] an auto-disabled account's audit entry is visible and legible in the existing admin UI without special-casing *(2026-10-16: run on the PC against the real page, 1440px and 390px, `tests/okta_sync_ui_check.py` 28/28. The admin Activity log card reads: Who `system:okta_sync`, Action `user deprovisioned by sync`, Type `user`, Item the username, Detail `okta_status: SUSPENDED, via: okta_sync` (a person missing from Okta reads `okta_status: MISSING`). Search for `okta_sync` and the User accounts filter both find the rows. No sideways scroll, no JavaScript errors. The disabled account is refused on its very next request; an account still active in Okta is not. A project super user does not see these rows: they belong to no project, so only admins do, the same as other user-management events. No code in `html/` changed.)* - [x] nothing here silently assumes `CR-019`'s activity view exists yet — this must work standalone *(2026-10-16: the check reads only the Activity log (AuditLog) card. The new Activity & usage card is on the page but is not read.)* --- **No UI was built.** The existing card renders the new rows legibly as is. Two things you might expect and did not get, both on purpose: no admin email on an auto-disable (D18 calls it a fast-follow; not built, not logged as a new item because D18 already names it), and no per-user history view in the User Directory (it has none today, and the task says not to build one). ### T13.6 — D18: verification - **Items:** `D18` - **Depends on:** T13.4, T13.5 - **Blocks:** nothing - **Surface:** `server/` - **Files:** as touched above **Do:** Full verification per `CLAUDE.md`. Beyond the usual run: specifically re-run T13.3's fail-closed test in isolation and confirm it still passes after T13.4's scheduling wrapper is in place — the scheduling layer must not introduce a path that swallows the client's error and proceeds anyway. **Done when:** - [ ] all `D18` acceptance criteria in `decisions-2026-09-17.md` are met or a failure is stated with a reason - [ ] the fail-closed behavior is verified end to end through the scheduled wrapper, not just the bare sync function - [ ] smoke test and `seed_demo.py` both still pass - [ ] full test suite passes --- ## Wave 13 exit criteria - [ ] `AUTH_SESSION_HOURS` defaults to 2, documented - [ ] the sync job runs on a schedule and correctly disables accounts Okta no longer shows as active - [ ] every auto-disable is individually audited with a clearly non-human actor - [ ] an Okta API failure of any kind changes zero accounts — verified, not assumed - [ ] the sync never re-enables an account - [ ] `D18` fully accounted for, no open acceptance criteria ## Release note (2026-10-16) T13.1 (commit `6cde6e3`) is held back from `main` until T14.1 lands, per the merge rule in `wave-12.md`. The release branch contains wave 11 and T13.2 to T13.5. `tests/session_idle_check.py` skips (exit 0) when `auth.maybe_refresh_token` is absent. Sessions keep the flat `AUTH_SESSION_HOURS` lifetime (default 12) until T13.1 lands. T13.6 result (2026-10-16, merged release tree, Edge on the PC): 47 test scripts, 45 pass. The two failures are not regressions. `token_check.py` exits 2 (CLI usage detail). `generalinfo_check.py` finds an old color-literal gap in `wp-creation-styles.css`. Alembic upgrade, downgrade, upgrade passed. Import check passed. ## T13.7: D22 dry run for the Okta sync **Item:** D22 (`docs/waves/decisions-2026-10-16.md`). Extends T13.3 and T13.4. **Done when:** - [x] `OKTA_SYNC_DRY_RUN` on: the sync fetches and matches, logs the accounts it would disable, and changes no account and writes no audit row (`tests/okta_sync_dry_run_check.py`) - [x] both guards (zero match, fail closed) still apply in a dry run - [x] flag off or unset: behavior is unchanged (`okta_sync_job_check.py` still passes) - [x] the startup line names the mode - [x] `.env.example`, `docker-compose.yml` and `DEPLOYMENT.md` describe the flag and the first-deploy steps - [x] mutation check: if the dry-run guard is removed, the new test fails Result 2026-10-16: all Okta sync tests and `security_check.py` pass in the sandbox. This task changes no frontend file. ## T13.8: run the stack in Docker on a PC **Item:** D22 (`docs/waves/decisions-2026-10-16.md`), as a way to check T13.7 and later builds before a deploy. **Done when:** - [x] one command starts the api, the database and the web server from the shipped compose file plus `docker-compose.local.yml` - [x] `http://localhost:8080/api/health` answers 200 and `/api/projects` answers 401 without a session - [x] every migration runs on Postgres (head `8e2cb3003f8a`) - [x] the api log shows the `Okta sync` startup line - [x] the steps are in `DEPLOYMENT.md`, "Run the stack on your own PC" - [x] the shipped `docker-compose.yml` and nginx config are not changed Result 2026-10-16 (Docker Desktop 29.7.2, Compose 5.4.0, Windows): passed. Three things in the shipped files stop a local run. The override handles the first two and the third is logged: 1. The web server publishes no port (the host's reverse proxy reaches it). The override publishes 8080 on loopback. 2. An existing `proxy` network on a PC can have no gateway, and Docker then does not publish ports. The override uses its own bridge. The stock nginx `default.conf` also answers "localhost" first and the app server answers only wp.controls.dev, so the override removes the stock file and makes the app server the default. 3. The backup container cannot start on Windows: `scripts/entrypoint.sh` has CRLF line endings (BL-070). The override turns the backup service off. ## T13.9: D23 sign in as an OAuth service app (private_key_jwt) **Item:** D23 (`docs/waves/decisions-2026-10-16.md`). Extends T13.2. **Done when:** - [x] with `OKTA_SYNC_CLIENT_ID` and `OKTA_SYNC_PRIVATE_KEY`, the sync gets an access token and lists users with `Bearer` (`tests/okta_sync_oauth_check.py`) - [x] the assertion verifies against the public key: `iss`, `sub`, `aud`, `kid`, life, `jti` - [x] RSA and EC keys; JSON and base64 forms - [x] a failed token request, a missing token, a DPoP token, a public key, or an unreadable key raises, and the users endpoint is never called - [x] `OKTA_API_TOKEN` still works and wins when both are set - [x] the startup line names the credential and holds no secret; no error message holds key text - [x] mutation checks: Bearer to SSWS, wrong `aud`, DPoP accepted, public-key check removed: each makes the test fail - [x] `.env.example`, `docker-compose.yml`, `DEPLOYMENT.md` describe the variables and the Okta app setup Result 2026-10-16: sandbox, fake Okta. Not yet run against the real tenant. No new dependency: PyJWT signs with `cryptography`, which Authlib already installs. T13.9 follow-up (2026-10-16): the first live deploy failed with "OKTA_SYNC_PRIVATE_KEY is not a JWK as JSON or as base64 of JSON". The first loader used strict base64, which rejects any space or line break, and it gave one message for every failure. The loader now forgives quote marks, spaces, line breaks, missing padding, the URL-safe alphabet, a byte-order mark and a one-key JWK Set, and each failure names its step (counts only, no key text). The new checks in `tests/okta_sync_oauth_check.py` fail against the first loader and pass now. T13.9 follow-up 2 (2026-10-16): the second deploy decoded the value but the text was not JSON. The loader now also names a PEM key, adds missing outer braces, unwraps a value that was encoded twice, and its "not JSON" message gives the length and the kind of first character (counts only). T13.9 follow-up 3 (2026-10-16): the third deploy decoded the base64 to 1,760 characters that start with a brace, but Python's strict JSON reader refused them (PowerShell accepted the same text). The loader now accepts control characters such as line breaks inside a string, curly quote marks and a trailing comma, removes spaces inside the key's number fields, and a real syntax error reports the line and column (position and rule only, never key text). ## T13.10: D24 DPoP for the Okta Management API **Item:** D24 (`docs/waves/decisions-2026-10-16.md`). Extends T13.9. **Done when:** - [x] auto mode: a plain Bearer token is tried first; `invalid_dpop_proof` makes the sync retry with DPoP (`tests/okta_sync_dpop_check.py`) - [x] each proof verifies: header (`dpop+jwt`, ES256, public jwk only), signature, `htm`, `htu` without query, current `iat`, one-time `jti`, `ath` on API calls, same key for token and API calls - [x] nonce challenges at the token endpoint and at the API are answered once, and the retries are bounded - [x] paging: a new proof for every page - [x] mode `on` and mode `off`; a DPoP-bound token with mode off is refused; each run makes a new key - [x] no secret in any message or the startup line; the SSWS path is unchanged - [x] mutation checks: query kept in `htu`, `ath` omitted, `jti` reused, nonce not retried (token and API), private key in the proof header, and auto detection removed each make a test fail - [x] `.env.example`, `docker-compose.yml`, `DEPLOYMENT.md` updated Result 2026-10-16: sandbox, strict fake Okta. Not yet run against the real tenant.