Okta
Purpose
Ingests Okta users, groups and memberships, applications, admin roles, MFA factors, trusted origins, devices, network zones, API token metadata, System Log streams, and policies with their rules.
Secret fields below accept either an AWS Secrets Manager ARN or a value pasted directly into Subimage's managed vault. See Secrets for details.
Required Fields
Provide an OAuth service app (okta_client_id and okta_private_key) or okta_api_key. Always set okta_org_id.
| Field | Secret? | Description |
|---|---|---|
okta_org_id |
No | Your Okta org subdomain, e.g. acme for https://acme.okta.com |
okta_client_id |
No | Client ID of an Okta API Services app |
okta_private_key |
Yes | The app's private key, as a PEM or a JWK |
okta_private_key_id |
No | Key ID (KID) of the app's public key. Not needed when the private key is a JWK that includes it |
okta_api_key |
Yes | Okta SSWS API token. Leave blank when using an OAuth service app |
okta_saml_role_regex |
No | Regex mapping Okta groups to AWS roles (default provided) |
okta_base_domain |
No | Okta base domain, e.g. oktapreview.com (default okta.com) |
Setup Steps
Option A — OAuth service app (recommended)
An OAuth service app gets short-lived access tokens limited to the scopes you grant, and is not tied to an admin user.
- In the Okta Admin Console, go to Applications → Applications → Create App Integration. Open the Classic experience tab, choose API Services, and click Next. The recommended Okta Integration Wizard tab does not offer this flow.
- Name the app (e.g.
SubImage), choose Use Okta-generated client ID, and click Save. Copy the Client ID. - Switch the app to key authentication. Okta creates the app with a client secret, but accepts only a private key when the app requests Okta API scopes. Add the key first, or Okta refuses the switch:
- Under Public keys, click Edit → Add key. Click Generate new key and save the private key Okta shows — it is displayed only once — or paste your own public key as a JWK. Click Done, then Save, and note the key's KID.
- Under Client Credentials, click Edit, choose Public key / Private key, click Save, and confirm. Okta deletes the unused client secret.
- Leave Require Demonstrating Proof of Possession (DPoP) as it is. Subimage works whether or not the app requires DPoP.
- On the Okta API Scopes tab, click Grant for each of these scopes:
okta.apiTokens.read,okta.apps.read,okta.authenticators.read,okta.devices.read,okta.groups.read,okta.logStreams.read,okta.networkZones.read,okta.policies.read,okta.roles.read,okta.trustedOrigins.read,okta.userTypes.read,okta.users.read. Okta refuses to issue a token if any of these is missing, and the sync fails with Okta OAuth service app rejected. - On the Admin roles tab, click Edit assignments, choose Super Administrator, and save. The app stays read-only — see Admin role and scopes. Okta asks you to reauthenticate before it saves an admin role.
- In Subimage, fill in:
okta_org_id— your org subdomainokta_client_id— the Client IDokta_private_key— the private key (or its AWS Secret ARN)okta_private_key_id— the KID
- Save the module.
Admin role and scopes
Okta checks two things on every request from a service app: one of the access token's scopes must allow the action, and the app's admin role must allow access to the resource. The scopes limit what the app can do; the admin role limits what it can see.
Subimage requests only read scopes, so the app cannot create, change, or delete anything in your Okta org, whatever admin role it has. That also makes a service app safer than an API token, which can do anything its creator can.
- Super Administrator (recommended): Subimage syncs every resource. The read scopes keep the app read-only.
- Read-only Administrator: Okta denies this role access to log streams, admin role assignments, the Admin Console session settings, and Okta's own apps such as the Admin Console and Dashboard. The sync skips those with a warning, and the Okta DISA STIG checks that need them are not evaluated instead of reporting a pass.
Option B — API token
An API token can do anything its creator can, so it forces a trade-off: a Super Administrator's token syncs every resource but can also change your Okta org, and a Read-only Admin's token misses the resources listed under Admin role and scopes. Option A avoids that trade-off.
- Create a service account (e.g.
svc_cartography). - Give it Read-only Admin or a custom read-only role with visibility into Users, Groups, Apps, Roles, Factors, Trusted Origins, Devices, Network Zones, API Tokens, Log Streams, and Policies.
- In Okta Admin Console → Security → API → Tokens → Create token and copy the value.
- In Subimage, fill in:
okta_org_id— your org subdomainokta_api_key— the token (or its AWS Secret ARN)okta_saml_role_regex— leave default unless you use a custom group naming scheme
- Save the module.
Notes
- If both an OAuth service app and an API token are set, the sync uses the service app.
- Okta System Log collection still authenticates with the API token. Keep
okta_api_keyset if you use it. - Okta expires API tokens after 30 days of inactivity.
- If the credential cannot read devices, the sync logs a warning, skips devices, and still syncs everything else.
- An API token gets its creator's admin role. A token created by a Read-only Admin is refused the same resources as the Read-only Administrator role above.
- Authentication and profile enrollment policies, and the Admin Console session settings, exist only in Okta Identity Engine orgs. Classic Engine orgs sync the other policy types.
- If the API token or service app is restricted to network zones, add your Subimage egress IP to one of those zones. From anywhere else Okta rejects the request.