setup

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.

tip

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

An OAuth service app gets short-lived access tokens limited to the scopes you grant, and is not tied to an admin user.

  1. 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.
  2. Name the app (e.g. SubImage), choose Use Okta-generated client ID, and click Save. Copy the Client ID.
  3. 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:
    1. 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.
    2. Under Client Credentials, click Edit, choose Public key / Private key, click Save, and confirm. Okta deletes the unused client secret.
  4. Leave Require Demonstrating Proof of Possession (DPoP) as it is. Subimage works whether or not the app requires DPoP.
  5. 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.
  6. 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.
  7. In Subimage, fill in:
    • okta_org_id — your org subdomain
    • okta_client_id — the Client ID
    • okta_private_key — the private key (or its AWS Secret ARN)
    • okta_private_key_id — the KID
  8. 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.

  1. Create a service account (e.g. svc_cartography).
  2. 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.
  3. In Okta Admin Console → Security → API → Tokens → Create token and copy the value.
  4. In Subimage, fill in:
    • okta_org_id — your org subdomain
    • okta_api_key — the token (or its AWS Secret ARN)
    • okta_saml_role_regex — leave default unless you use a custom group naming scheme
  5. 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_key set 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.