6.3 KiB
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_IDandOKTA_SYNC_PRIVATE_KEY(a JWK as JSON, or as base64 of that JSON). The sync signs a JWT (RS256 or ES256, from the key'salg;kidgoes in the header;issandsubare the client ID;audis<org>/oauth2/v1/token; life 5 minutes; a newjtieach time) and posts it to<org>/oauth2/v1/tokenwithgrant_type=client_credentialsandscope=okta.users.read.- The access token is used as
Authorization: Beareron/api/v1/users. It is requested again at the start of each run. It is not stored. OKTA_API_TOKENstill works. If both are set, the token wins. A deploy that sets only a token is unchanged.- A DPoP token (
token_typenot 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.
D24: DPoP for the Okta Management API calls
Asked by: Matt Mabrey, 2026-10-16. Extends: D23. Task: T13.10.
Why: The first live token request with the service-app key ended with
error invalid_dpop_proof. The Okta app requires DPoP (RFC 9449). With DPoP, every
request carries a signed proof from a key that only the caller holds, so a stolen
access token alone does not work. The choice was to ask the Okta admin to switch DPoP
off, or to build it. Matt chose to build it.
Decision:
OKTA_SYNC_DPOPisauto(default),onoroff. In auto mode the sync asks for a plain Bearer token first. If Okta answersinvalid_dpop_proof, the sync asks again with DPoP. So one build works whether the Okta app requires DPoP or not.- Each run makes its own throwaway EC P-256 key. It is held in memory only, never stored, logged or configured. The public half goes in each proof header.
- Each request gets its own proof (ES256,
typdpop+jwt):htm,htuwithout the query, a one-timejti,iat, the server's latestnonce, and on an API callath(a hash of the access token). The same key is used for the token request and the API calls. A new client assertion is built for every token attempt. - A nonce challenge is answered once per request, at the token endpoint and at the API. The token request is tried at most 4 times.
- A DPoP-bound token is sent as
Authorization: DPoP <token>. If the setting isoffand Okta returns a DPoP-bound token, the sync stops with a clear message.
Rules from D18 and D23 that stay: fail closed; the key, the assertions, the proofs and the access token are never logged or put in an error message; an error carries the HTTP status and Okta's short error code only. The SSWS token path is unchanged.
Not verified: this has been tested only against a fake Okta that follows the RFC. The first run against the real tenant is the real test.
D25: the session limit is 8 hours for now
Decided by: Matt Mabrey, 2026-10-17. Closes: the 2-versus-8 question in wave-13.md. Task: T13.11.
The conflict: the wave 13 exit criteria said AUTH_SESSION_HOURS defaults to 2. T13.1's own text and
the T13.1 code say 8. The shipped default on main was 12.
Decision: The default is 8 hours. This replaces the exit criterion of 2 hours.
AUTH_SESSION_HOURSdefaults to 8 inserver/auth.py,docker-compose.yml,server/.env.exampleandDEPLOY-login-portal.md. A value that is set still wins.- Until T13.1 lands, 8 hours is one flat limit from the moment of sign-in, with no sliding. Once T13.1 lands, the same variable is the absolute ceiling and an idle timer sits under it. The default does not change then.
- A person who signs in at the start of a shift is signed out 8 hours later, whatever they were doing. Signing in again needs Okta to be reachable.
Open, for wave 14: how the limit works for a crew that is offline. wave-14.md sets that rule.
Not decided here: the idle time (T13.1 proposes 30 minutes). It is a proposed value, not a decision.