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
|
unreachable for everyone, including admins, until Okta is restored — the same
|
||||||
posture the abandoned LDAPS design took, carried forward deliberately (D16).
|
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
|
## Permissions roles
|
||||||
|
|
||||||
`User.role` is the **permissions** role; `User.project_role` is the person's **job
|
`User.role` is the **permissions** role; `User.project_role` is the person's **job
|
||||||
|
|||||||
Reference in New Issue
Block a user