Skip to content

Set up the Okta connector

Okta is set up as a connected application in the App Registry. There is no separate Okta connector page. (Connectors → Flat-file is for CSV imports and has nothing to do with Okta.) To create the application, test it, save credentials and sync, you need the Identity Admin, Tenant Owner or Super Admin role.

1. Prepare Okta

Choose one way for AtmanID to sign in to Okta:

Method What you create in Okta AtmanID fields
OAuth 2.0 (recommended) An API service app that uses public-key client authentication, with AtmanID’s public key uploaded to it Auth Method = PRIVATE_KEY_JWT, OAuth Client ID, AtmanID Signing Key (PEM), optional Signing Key ID (kid) and Okta API Scopes
API token (legacy) Okta Admin → Security → API → Tokens API Token (legacy SSWS); leave Auth Method blank or set it to PAT

With OAuth, AtmanID only ever requests these four scopes. Grant them on the service app under Okta API Scopes:

Scope Needed for
okta.users.read, okta.groups.read Importing users, groups and memberships. These two are the default when Okta API Scopes is left blank.
okta.users.manage Creating accounts (joiners) and deactivating users (leavers)
okta.groups.manage Assigning groups (movers) and removing group access

Any other scope is refused, including the okta.* wildcard and okta.apps.manage. Each OAuth token lasts one hour. Once a connector uses OAuth, only a Super Admin can switch it back to an API token.

2. Add Okta as an application

  1. Go to Identity & Access → Applications → Registry and click Add Application.
  2. Choose Type: pick Connected.
  3. App Details: enter an Application Name, such as “Okta Production”. Description is optional.
  4. Connector: pick Okta. If the name contains “okta”, Okta is already selected for you. If you pick nothing, the app is created as a generic SCIM app instead.
  5. Click Create Application. You enter credentials after the app exists, not in this wizard.

3. Enter credentials and test

  1. Open the application and go to the Config tab → Connection & sync → Configure credentials.
  2. Enter Okta Domain (for example your-org.okta.com) and the fields for your chosen method. Fields marked with an asterisk are required for the method in Auth Method: API Token (legacy SSWS) for the API token, or OAuth Client ID and AtmanID Signing Key (PEM) for OAuth. Leave the other method’s fields blank.
  3. Click Test Connection. This tests what you typed. A good result reads “Connected to org name in Nms”. With OAuth, the test reads one page of users (scope okta.users.read) and shows your Okta domain in place of the org name.
  4. Click Save Credentials. Credentials are encrypted before they are stored and are never shown again.

4. Run the first sync

  1. On the Config tab, under Entitlement discovery, click Discover. This imports your Okta groups as entitlements. Do this first: memberships are only synced for groups that have already been discovered.
  2. On the Accounts tab, click Sync Now. When it finishes you see “Sync complete” with counts of found, new and updated accounts.
  3. Check the result on the Activity tab → Sync History. For every connector at once, use Identity & Access → Connectors → Sync health.

What is imported

Imported Details
Users Active Okta users only, with login, display name, email, department, title, user type, last login and created date. Up to 50 pages of 200 users per sync.
Groups Brought in as entitlements by Discover (one page of up to 200 groups). Risk is guessed from the group name.
Group memberships Updated after every successful sync, for groups already discovered

Okta applications, app assignments, MFA factors and admin roles are not imported. A user who is no longer returned by Okta is marked disabled in AtmanID, not deleted.

Schedule

Every connected application with saved credentials is synced once a day at 04:30 UTC. The sync covers accounts and then memberships. You cannot change the time or frequency for a single connector. Okta supports incremental (delta) sync in the code, but the Delta Sync button is not offered for Okta.

Audit events

APPLICATION_CREATED, APP_CREDENTIALS_UPDATED, CONNECTOR_TEST_OK or CONNECTOR_TEST_FAILED, ENTITLEMENT_DISCOVERY_RUN and APP_SYNC_EXECUTED. The scheduled sync’s APP_SYNC_EXECUTED shows scheduler as the actor. See Navigate the audit trail.

Troubleshooting

Message What to check
Invalid API token — verify SSWS token and scopes The API token is wrong or revoked
Okta refused the OAuth token (HTTP 401 or 403) Test Connection reads users, so the service app needs okta.users.read. Also check the client ID and that Okta holds the matching public key.
Auth failed listing users The credentials stopped working after they were saved
Okta rate limit — retry in a minute Okta returned 429. Each page is already retried twice before this appears.
Connection timed out (10s) Check Okta Domain. There is no separate “wrong domain” message.
Okta token exchange failed The error names the scopes AtmanID asked for. Grant exactly those, or narrow Okta API Scopes.
No credentials configured for this application Save credentials before you click Sync Now
A sync is already running for this application. Wait for the current run to finish

© AtmanID · Privacy