T13.9: sign in to the Okta Management API as an OAuth service app, private_key_jwt (D23)

This commit is contained in:
2026-10-16 15:29:32 -07:00
parent ad1b8273c0
commit d137d690f9
7 changed files with 422 additions and 11 deletions

View File

@@ -29,3 +29,35 @@ 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.

View File

@@ -370,3 +370,21 @@ and the third is logged:
1. The web server publishes no port (the host's reverse proxy reaches it). The override publishes 8080 on loopback.
2. An existing `proxy` network on a PC can have no gateway, and Docker then does not publish ports. The override uses its own bridge. The stock nginx `default.conf` also answers "localhost" first and the app server answers only wp.controls.dev, so the override removes the stock file and makes the app server the default.
3. The backup container cannot start on Windows: `scripts/entrypoint.sh` has CRLF line endings (BL-070). The override turns the backup service off.
## T13.9: D23 sign in as an OAuth service app (private_key_jwt)
**Item:** D23 (`docs/waves/decisions-2026-10-16.md`). Extends T13.2.
**Done when:**
- [x] with `OKTA_SYNC_CLIENT_ID` and `OKTA_SYNC_PRIVATE_KEY`, the sync gets an access token and lists users with `Bearer` (`tests/okta_sync_oauth_check.py`)
- [x] the assertion verifies against the public key: `iss`, `sub`, `aud`, `kid`, life, `jti`
- [x] RSA and EC keys; JSON and base64 forms
- [x] a failed token request, a missing token, a DPoP token, a public key, or an unreadable key raises, and the users endpoint is never called
- [x] `OKTA_API_TOKEN` still works and wins when both are set
- [x] the startup line names the credential and holds no secret; no error message holds key text
- [x] mutation checks: Bearer to SSWS, wrong `aud`, DPoP accepted, public-key check removed: each makes the test fail
- [x] `.env.example`, `docker-compose.yml`, `DEPLOYMENT.md` describe the variables and the Okta app setup
Result 2026-10-16: sandbox, fake Okta. Not yet run against the real tenant.
No new dependency: PyJWT signs with `cryptography`, which Authlib already installs.