64 lines
3.3 KiB
Markdown
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.
|