From bbfa403117f286f44aed205b9908e4b905e9052b Mon Sep 17 00:00:00 2001 From: Matt Mabrey Date: Fri, 16 Oct 2026 12:05:03 -0700 Subject: [PATCH] D18 docs: admin instructions for accounts the Okta sync disabled (T13.6) New DEPLOYMENT.md section: how to see what the sync did, how to re-enable a person (fix Okta first, then Enable in the User Directory), who may do it (admin; super user only for exclusive-scope accounts), the host CLI when no admin can sign in, and how to turn the sync off if it disabled the wrong people. --- DEPLOYMENT.md | 66 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md index 9d411ac..e79d392 100644 --- a/DEPLOYMENT.md +++ b/DEPLOYMENT.md @@ -413,6 +413,72 @@ Directory page — no shell access needed. unreachable for everyone, including admins, until Okta is restored — the same posture the abandoned LDAPS design took, carried forward deliberately (D16). +### Accounts the Okta sync disabled (D18) + +**Who this is for:** app admins, and project super users who manage accounts. + +When `OKTA_API_TOKEN` is set, the `api` container asks Okta every 15 minutes +(`OKTA_SYNC_INTERVAL_SECONDS`) who is still active. It **disables** a local +account when the person is missing from Okta's list, or when Okta shows the +status SUSPENDED or DEPROVISIONED. A password expiry, a lockout, or a recovery +in progress does not disable anyone. With no token set, the sync is off and the +startup log says `Okta sync DISABLED`. + +The sync only ever disables. **It never re-enables an account.** A person comes +back only when an admin enables the account by hand. + +**How to see what the sync did** + +1. Open the **Admin Console** (`admin.html`). Find the **Activity log** card. +2. Click **Refresh**. Search for `okta_sync`, or set the type to **User accounts**. +3. A row from the sync reads: Who `system:okta_sync`, Action `user deprovisioned + by sync`, Item the username, Detail `okta_status: SUSPENDED` (or `MISSING` if + the person was not in Okta's list at all). + +Only app admins see these rows. They belong to no project. + +**How to re-enable a person** + +1. **Fix the person in Okta first.** Ask the Okta admin to make the person ACTIVE + again (or to restore them, for a rehire). If you skip this step, the next sync + cycle (up to 15 minutes later) disables the account again. +2. Open the **User Directory** (`users.html`). +3. Find the person. A disabled account shows the **Enable** button on its row. + Click it. +4. The person can sign in on their next attempt. The app writes a `user enabled` + row to the Activity log under your name. + +**Who may do step 3** + +* An **app admin** may enable any account. +* A **project super user** may enable an account only if every project the person + belongs to is a project that super user administers. If the person is also on a + project that the super user does not administer, the row is read-only and shows + the reason. An app admin must make the change. +* Nobody can change their own account. + +**If no admin can sign in** (for example, a bad sync run disabled every admin), +use the shell on the host. Replace `alice` with the username: + +```bash +docker compose exec api python -m server.manage_users list +docker compose exec api python -m server.manage_users enable alice +``` + +**If the sync disabled the wrong people** + +1. Turn the sync off. Remove `OKTA_API_TOKEN` from `.env` and restart the api + (`docker compose up -d api`). The sync starts only when the token is set. +2. Find the cause before you turn it on again. The usual cause is that the Okta + profile attribute does not match `users.username`. See + `OKTA_SYNC_PROFILE_ATTRIBUTE` in `server/.env.example`. +3. Enable the people who were disabled by mistake (steps above). +4. Set the token again and restart. + +If the sync cannot reach Okta, or Okta gives an answer the sync cannot trust, the +sync changes **no** account in that cycle and writes a line to the api log: +`docker compose logs api | grep "Okta sync"`. + ## Permissions roles `User.role` is the **permissions** role; `User.project_role` is the person's **job