Files
Project-SDE-WP-Suite/docs/waves/decisions-2026-10-16.md

64 lines
3.3 KiB
Markdown

# Decisions: October 16, 2026
## D22: dry run for the Okta deprovisioning sync
**Asked by:** Matt Mabrey, 2026-10-16. **Extends:** D18 (wave 13). **Task:** T13.7.
**Why:** The sync disables a local account when Okta does not list the person.
If the Okta profile attribute is wrong for some accounts, the first live run can
disable people who have not left (see BL-069). The attribute `profile.login` is
the default for `preferred_username`. It is not confirmed against the tenant, and
the person who deploys has no access to the Okta admin console.
**Decision:** Add the environment variable `OKTA_SYNC_DRY_RUN`.
- Values `1`, `true`, `yes`, `on` (any case) turn it on. Any other value, or no
value, leaves the sync live. It is off by default, so a deploy that does not set
it behaves as before.
- In a dry run the sync does every step of a live run: the fetch, the match, the
zero-match guard and the fail-closed rules. It then changes no account and writes
no audit row.
- It logs one line for each account it would disable, and one summary line with the
number of Okta users, active local accounts, matches, and accounts that would be
disabled. Read them with `docker compose logs api | grep "Okta sync"`.
- The startup line shows the mode.
**Not decided here:** a limit on accounts disabled in one run, and a rule to keep the
last active admin (BL-069). The dry run lets a person see the result before the
first live run. It does not stop a bad live run.
**Rules from D18 that stay:** fail closed, only disable, one audit row for each
change, actor `system:okta_sync`.
## D23: sign in to the Okta Management API as an OAuth service app
**Asked by:** Matt Mabrey, 2026-10-16. **Extends:** D18, T13.2. **Task:** T13.9.
**Why:** The first deploy of the sync ended with `Okta answered HTTP 401`. The
credential that Okta security gave Matt is an API Services app that uses client
authentication `private_key_jwt`. It is a private key (a JWK with the fields `kty`,
`use` and `kid`), not an SSWS API token. The sync sent that value as an SSWS token,
and Okta refused it.
**Decision:** The sync accepts a second credential.
- `OKTA_SYNC_CLIENT_ID` and `OKTA_SYNC_PRIVATE_KEY` (a JWK as JSON, or as base64 of
that JSON). The sync signs a JWT (RS256 or ES256, from the key's `alg`; `kid` goes
in the header; `iss` and `sub` are the client ID; `aud` is `<org>/oauth2/v1/token`;
life 5 minutes; a new `jti` each time) and posts it to `<org>/oauth2/v1/token`
with `grant_type=client_credentials` and `scope=okta.users.read`.
- The access token is used as `Authorization: Bearer` on `/api/v1/users`. It is
requested again at the start of each run. It is not stored.
- `OKTA_API_TOKEN` still works. If both are set, the token wins. A deploy that sets
only a token is unchanged.
- A DPoP token (`token_type` not Bearer) is refused with a clear message.
**Rules from D18 that stay:** fail closed. Any problem with the key, the token
request or the user list raises an error, and the sync changes no account. The key,
the signed JWT and the access token are never logged and never put in an error
message. An error carries the HTTP status and the Okta error code only when that
code is a short lower-case word.
**Not decided here:** how often the key is replaced. A key is registered on the Okta
app and has no expiry that this code checks.