T13.9: sign in to the Okta Management API as an OAuth service app, private_key_jwt (D23)
This commit is contained in:
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user