T13.9: sign in to the Okta Management API as an OAuth service app, private_key_jwt (D23)
This commit is contained in:
@@ -408,13 +408,41 @@ posture the abandoned LDAPS design took, carried forward deliberately (D16).
|
||||
|
||||
**Who this is for:** app admins, and project super users who manage accounts.
|
||||
|
||||
When `OKTA_API_TOKEN` is set, the `api` container asks Okta every 15 minutes
|
||||
When Okta credentials are set (`OKTA_API_TOKEN`, or the service-app pair below), the `api` container asks Okta every 15 minutes
|
||||
(`OKTA_SYNC_INTERVAL_SECONDS`) who is still active. It **disables** a local
|
||||
account when the person is missing from Okta's list, or when Okta shows the
|
||||
status SUSPENDED or DEPROVISIONED. A password expiry, a lockout, or a recovery
|
||||
in progress does not disable anyone. With no token set, the sync is off and the
|
||||
startup log says `Okta sync DISABLED`.
|
||||
|
||||
**Two ways to sign in to Okta.** Set one of them.
|
||||
|
||||
- *API token (SSWS):* set `OKTA_API_TOKEN` to the token string. It has about 40
|
||||
letters, digits, hyphens and underscores, and no quote marks.
|
||||
- *Service app with a private key (`private_key_jwt`):* set `OKTA_SYNC_CLIENT_ID`
|
||||
(the app's client ID, it starts with `0oa`) and `OKTA_SYNC_PRIVATE_KEY` (the
|
||||
private key as a JWK). The key starts with `{` and has fields such as `kty`,
|
||||
`kid` and `d`. In Portainer, encode it as base64 first, because Portainer can
|
||||
change the quote marks in JSON. In Windows PowerShell, save the key to a file
|
||||
`key.json` and run:
|
||||
|
||||
[Convert]::ToBase64String([IO.File]::ReadAllBytes("key.json"))
|
||||
|
||||
Paste the one-line result as the value. Delete `key.json` afterward. The key is
|
||||
a secret: never put it in Git, a ticket, or a chat.
|
||||
|
||||
The Okta admin must set up the app as follows: the app type is API Services; the
|
||||
scope `okta.users.read` is granted on the Okta API Scopes tab; an admin role
|
||||
that can read users (for example Read-only Administrator) is assigned to the app;
|
||||
and "Require Demonstrating Proof of Possession (DPoP)" is off. If both
|
||||
`OKTA_API_TOKEN` and the service-app pair are set, the token is used.
|
||||
|
||||
The startup line in the log says which credential is in use. A failed sign-in
|
||||
shows the HTTP status and the Okta error code, for example
|
||||
`Okta answered HTTP 400 to the token request, error invalid_scope`. Common codes:
|
||||
`invalid_client` (wrong client ID or key, or the key is not registered on the app),
|
||||
`invalid_scope` (the scope is not granted), `access_denied` (no admin role assigned).
|
||||
|
||||
**First deploy: use the dry run.** Set `OKTA_SYNC_DRY_RUN=true` in `.env` (or the
|
||||
Portainer stack environment) with the token, then run `docker compose up -d --build api`.
|
||||
The sync runs as normal but changes no account and writes no audit row. Read the
|
||||
|
||||
Reference in New Issue
Block a user