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:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user