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.
This commit is contained in:
2026-10-16 12:05:03 -07:00
parent 253886923c
commit bbfa403117

View File

@@ -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