Matt Mabrey
c74289aa0d
Decision, raised during T10.4 hazard review: - Admin bootstrap: manage_users.py moves from creating an admin account to promoting an existing one, by username, on a row Okta's JIT provisioning (T10.3) already created. Rejected blind account creation — the exact OKTA_IDENTITY_CLAIM format is still unconfirmed by security, and a hand-typed username that doesn't match it produces an orphaned second account instead of promoting the real one. Ongoing (non-bootstrap) admin naming needs no new work: html/users.js's existing role dropdown already handles it. - Break glass: none, by design, matching the precedent already on record for the abandoned LDAPS design (D13/D14) rather than assumed to carry over untested. If Okta is unreachable, the app is unreachable for everyone until Okta is restored. Rejected a toggleable emergency local login — it would reintroduce the stored credential D15 exists to eliminate. Also corrects T10.4's scope in wave-10.md: hazard review found real call sites of hash_password/verify_password/password_problem the original bullet didn't name (create_user(), admin_reset_password(), users.js's admin forms, browser_check.py/launcher_check.py fixtures), plus a verification-gate ordering problem (smoketest.py and seed_demo.py authenticate via POST /api/auth/login, which T10.4 removes, and both are named explicitly in CLAUDE.md's verification section). Fixed by having T10.4 switch both scripts to mint a session with auth.create_token() directly, the same technique browser_check.py already uses, rather than waiting on T10.7. D16
78 lines
4.2 KiB
Markdown
78 lines
4.2 KiB
Markdown
# Decisions — 2026-09-03
|
|
|
|
## D16: Okta admin bootstrap, break-glass posture, and the real scope of T10.4
|
|
|
|
Raised during hazard review for T10.4 (remove the local password path). D15 settled
|
|
*that* local passwords go away and Okta OIDC is the sole replacement; it did not settle
|
|
how an admin account gets named once there is no password to set, or what happens if
|
|
Okta itself is unreachable. Both are decided here.
|
|
|
|
### Admin bootstrap
|
|
|
|
`server/manage_users.py` stays the bootstrap tool — its own docstring already says so
|
|
("the `/api/auth/users` endpoint needs an existing admin, so you have to bootstrap one
|
|
here") — but it changes from *creating* an account to *promoting* one:
|
|
|
|
- An operator with shell/DB access on the server runs it against an account that
|
|
already signed in through Okta once and was JIT-provisioned by T10.3 (landing at
|
|
`project_user`, per that task). The command sets `role = admin` on that existing row
|
|
by username.
|
|
- It does **not** create a `User` row from scratch and does not touch `password_hash`
|
|
(the column is gone after T10.4's migration).
|
|
|
|
Rejected: minting a brand-new admin row by hand-typed username. `OKTA_IDENTITY_CLAIM`'s
|
|
exact format is still unconfirmed by security (open item carried from D15/wave-10.md).
|
|
A hand-typed username that doesn't exactly match what Okta actually sends produces a
|
|
second, orphaned account instead of promoting the real one. Promoting an
|
|
already-JIT-provisioned row sidesteps that entirely — it never has to guess the future
|
|
claim value.
|
|
|
|
Ongoing (non-bootstrap) admin naming needs no new work: `html/users.js` already has a
|
|
live role dropdown (`roleSelect`, gated by server-supplied `grantable_roles`) that lets
|
|
an existing admin promote any other account, including one JIT-provisioned via Okta.
|
|
That path is unrelated to the password removal and keeps working unchanged.
|
|
|
|
### Break glass
|
|
|
|
No break-glass path, by design. If Okta is unreachable or misconfigured, the app is
|
|
unreachable for everyone, including admins, until Okta is restored.
|
|
|
|
This matches the precedent already on record for the abandoned LDAPS design (D13/D14):
|
|
"LDAPS is the *only* path, no local fallback, no break-glass." Carried forward
|
|
deliberately rather than assumed to still apply, given Okta's failure modes differ from
|
|
an internal LDAP bind — considered and confirmed, not defaulted into.
|
|
|
|
Rejected: a toggleable emergency local login gated behind an env flag. It would
|
|
reintroduce a stored local credential, exactly what D15 exists to eliminate, for a
|
|
scenario (Okta down) judged less likely and less costly than the standing risk of a
|
|
forgotten emergency backdoor.
|
|
|
|
The server-shell CLI (`manage_users.py`, promoting an existing row) is not a formal
|
|
break-glass mechanism — it cannot help if no account has ever signed in through Okta —
|
|
but it is the same trust tier as "someone with SSH/container access to prod could
|
|
already edit the database directly," and it costs no new engineering.
|
|
|
|
### T10.4 scope correction
|
|
|
|
Hazard review found real call sites of `hash_password` / `verify_password` /
|
|
`password_problem` that the original T10.4 bullet in `wave-10.md` didn't name and that
|
|
break the moment those functions are deleted:
|
|
|
|
- `create_user()` and `admin_reset_password()` in `server/app.py` (the admin console's
|
|
"add user" and "reset password" routes).
|
|
- `html/users.js`'s "add user" form (`nu-password` field) and "Reset password" button.
|
|
- `server/manage_users.py`'s `create`, `create-admin`, and `reset-password` subcommands
|
|
(see bootstrap section above for its replacement).
|
|
- `tests/browser_check.py` and `tests/launcher_check.py`, which call
|
|
`auth.hash_password()` to seed fixture rows.
|
|
|
|
Also found: `server/smoketest.py` and `server/seed_demo.py` authenticate via
|
|
`POST /api/auth/login`, which T10.4 removes, and CLAUDE.md's own verification section
|
|
names both scripts as required checks. Fix folded into T10.4 rather than deferred to
|
|
T10.7: both scripts switch to minting a session with `auth.create_token()` and setting
|
|
the cookie directly, the same technique `tests/browser_check.py` already uses instead
|
|
of scripting a login form. No live Okta tenant needed, and T10.4 no longer depends on
|
|
T10.7's timing.
|
|
|
|
`wave-10.md`'s T10.4 bullet is updated to reflect this full scope.
|