Okta Connector

The Okta connector imports users, groups, and group memberships from an Okta org into IdentityMesh through the Okta REST API. It runs as a standard IdentityMesh plug-in DLL — drop it into the engine’s Connectors/ folder, give it your org domain and an API token, and the engine handles scheduling, watermarking, and projection into the mesh.

This runbook covers phase 1: import only. Write-back (creating users, modifying group membership, deactivating accounts) is on the roadmap as phase 2 and is called out explicitly at the end of this document.

If you are migrating from Okta to Entra ID (or running both side by side during a transition), this connector composes with the Entra ID connector — both project into the same mesh objects, and the merge behaviour is governed by the join rules configured in the Admin UI.

At a glance

Prerequisites

You will need:

1. An Okta org where you have administrator access. Standard, developer, and preview orgs all work — the API surface is identical. The org domain (e.g. contoso.okta.com, contoso.oktapreview.com, or a custom domain) is required to configure the connector.

2. An admin who can create API tokens. API tokens inherit the permissions of the user who created them, so the operator should already hold a read-only admin role to enforce least privilege. Avoid creating the token from a Super Admin account.

3. An IdentityMesh deployment with:

   • The Okta connector DLL in the host’s Connectors/ folder. Both the Sync Engine MSI and the Relay Agent MSI install it; nothing to copy (see relay-agent.md).
   • Read access to the IM_Secrets table (or to your Key Vault / Vault backend if you’ve migrated secrets per secrets-keyvault.md / secrets-vault.md).

4. Outbound HTTPS to your Okta org domain from whichever host runs the import — the central sync engine, or a relay agent if you have routed this connector through one. No inbound firewall rules are needed.

Step 1 — Create an Okta API token

1. Sign in to your Okta admin console at https://<your-org>.okta.com/admin as an org administrator.

2. Navigate to Security → API → Tokens.

3. Click Create Token.

   Field	Value
   Name	IdentityMesh-Import
   Scope	(inherits the creator’s role)

4. Copy the token VALUE immediately — Okta only displays it once. There is no way to retrieve a token after this dialog closes; if you miss it, delete the token and create a new one.

5. Calendar a 90-day rotation. Okta tokens auto-expire after 30 days of inactivity, and continue to work indefinitely while in active use; either way, rotate every 90 days to bound exposure if a token is ever leaked.

These tokens grant whatever permissions the creating admin holds. Phase 1 needs only read access to users and groups — assign the token-creator a read-only admin role rather than Super Admin.

Phase 2: OAuth2 service apps (private-key JWT)

Phase 2 of this connector will add support for OAuth2 service apps using private-key JWT bearer tokens. That mode is more enterprise- friendly than static API tokens (key-scoped, per-app audit, no token inactivity expiry) but adds setup complexity. Phase 1 ships static API tokens only; if you need OAuth2 service apps today, open a feature request.

Step 2 — Provision the secret in IdentityMesh

The connector reads its API token through IdentityMesh’s secret store. Use a stable secret reference name like secret://okta/<org-name>/apitoken.

Store it with the secretscli tool that ships with the Sync Engine, run on the engine host:

secretscli set secret://okta/contoso/apitoken "<paste-token-from-step-1>"

The tool DPAPI-encrypts the token with the scheme described in secrets-and-dpapi.md and stores it in IM_Secrets. Confirm it with secretscli exists <ref>.

If you have migrated to Azure Key Vault (secrets-keyvault.md) or HashiCorp Vault (secrets-vault.md) instead of DPAPI, store the token in your vault under the same reference name. IdentityMesh resolves the reference at run time — the connector configuration is the same either way.

Step 3 — Configure the connector

Create the connector through the Admin UI or by POSTing to /api/connectors. The configuration is two JSON documents.

ConfigJson

{
  "OrgDomain": "contoso.okta.com",
  "UserSearchFilter": null,
  "PageSize": 200,
  "ImportUsers": true,
  "ImportGroups": true,
  "ImportMemberships": true,
  "ExternalIdAttribute": "id"
}

AuthJson

{
  "Mode": "ApiKey",
  "ApiKey": "secret://okta/contoso/apitoken"
}

The ApiKey field is a secret reference, not the plaintext token. IdentityMesh resolves it at run time and only the resulting SSWS header value is held in memory for the lifetime of one import.

What gets synced

User attributes

The connector flattens the standard Okta profile sub-object onto the mesh attribute store, plus a small set of top-level lifecycle fields.

Custom Okta profile attributes (the extensible profile schema), MFA factors, app assignments, and group rules are not imported in phase 1 — see “What’s deferred to phase 2”.

Group attributes

Group members

Membership is imported on the group, as a member attribute holding the members’ Okta user IDs joined with ; — the same shape as an Active Directory group’s member. A group with no members has no member attribute at all. Okta does not nest groups natively, so the list only ever holds user IDs.

Membership is deliberately not imported as objects of its own. A standalone membership row can never become a mesh relationship: the join engine only joins an object to a mesh object of the same type, and an inbound flow holds one value per attribute. Edges come from a multi-valued reference attribute on the group, so that is what the connector imports.

To turn the list into mesh membership you need three things:

1. The member / Group schema row: reference, multi-valued. The installer’s database step creates it on every install and upgrade, so an upgraded system already has it. A database updated outside the installer needs the database step run (see Running the database step yourself) before the services start.
2. An inbound attribute flow on this connector for the Group type: member → member. Inbound flows are rule-driven; without the rule the attribute never reaches the mesh.
3. Join rules for User and Group that anchor on id. The engine matches each member ID against the mesh anchor, so users anchored on login never resolve.

The engine then writes one member relationship from the group to each resolved member, prunes the ones no longer listed on the next import, and skips members with no mesh object yet (they resolve on a later run).

Scoping the user set

A typical Okta org has more accounts than IdentityMesh needs to manage — service accounts, deactivated former employees, partner guests. Use UserSearchFilter to narrow the set.

Examples:

{ "UserSearchFilter": "status eq \"ACTIVE\"" }

Only currently active users. Skips STAGED, SUSPENDED, DEPROVISIONED, and other non-active lifecycle states.

{ "UserSearchFilter": "profile.userType eq \"Employee\"" }

Only employee accounts (assuming you populate userType on the profile schema).

{ "UserSearchFilter": "profile.department eq \"Engineering\"" }

Only users in a particular department.

The filter is an Okta search filter — see the Okta filter docs for the full grammar and supported operators.

Note that Okta does not offer an equivalent filter on the /groups endpoint; if you need to scope groups, use a naming convention (e.g. prefix groups intended for IdentityMesh with IM-) and post-filter in the mesh.

Watermark behaviour

Okta does not provide a true delta endpoint. Instead the connector uses the lastUpdated timestamp as a filter:

• Full mode (no watermark, or Mode = Full in the request): walks the full /api/v1/users and /api/v1/groups lists.
• Delta mode: users are filtered by lastUpdated gt "<stored timestamp>". Groups are filtered by (lastUpdated gt "<stored timestamp>" or lastMembershipUpdated gt "<stored timestamp>"), because Okta bumps lastMembershipUpdated — not lastUpdated — when a member is added or removed. A filter on lastUpdated alone would never re-read a group whose only change is membership.

The connector encodes one high-water timestamp per object type into a tiny JSON wrapper so a single watermark string covers everything:

{ "u": "2026-04-22T08:15:30.000Z", "g": "2026-04-21T17:00:00.000Z" }

The group mark advances over the later of the two group timestamps, so a membership-only change is read once and not on every run after. Memberships have no cursor of their own: every group the delta returns has its full member list re-read, and its member attribute always carries the whole list.

Because the watermark is a plain ISO 8601 timestamp (not an opaque delta link), an operator can read it directly out of the database when investigating a stuck sync, and even hand-edit it to force a particular cutover. That is materially easier to debug than Graph’s deltaLink tokens.

Hard-delete detection (important gap)

The lastUpdated filter only fires when a user is modified. Okta does not always raise a modification event when a user is hard-deleted from the directory, so deletes — particularly the DEPROVISIONED → purged flow — may not surface through delta runs.

The connector partially mitigates this: any user it sees with status = DEPROVISIONED is emitted as a Delete change. But this only catches deprovisioning that is observable through lastUpdated.

Operator action: schedule a periodic full sync — typically weekly — so the connector walks the full user list end-to-end and the mesh can detect users that have been hard-deleted from Okta since the last full pass. Configure this through the Admin UI’s schedule editor or by setting Mode = Full on a recurring run.

Phase 2 will close this gap properly by reading the Okta System Log (/api/v1/logs) for user.lifecycle.delete events. Until then, the periodic full sync is the supported workaround.

Throttling and rate limits

Okta enforces rate limits per-org and per-app. Bulk reads on large orgs can occasionally trip them — particularly the per-org concurrent request limit and the per-endpoint per-minute limits.

The connector handles Retry-After automatically:

• On HTTP 429 (Too Many Requests) or 503 (Service Unavailable), the connector sleeps for the duration in the Retry-After response header (or capped exponential backoff if the header is absent).
• It retries up to 3 times before surfacing the error to the engine.
• The maximum back-off is 30 seconds — anything longer is treated as a control-plane issue worth surfacing.

If you see Retry-After log entries during normal operation:

• Lower PageSize from 200 to 100. Fewer rows per request reduces the chance of long-running queries that count against the per- resource budget.
• Spread connector schedules so the user, group, and membership passes don’t all fire at the same minute.
• Check the X-Rate-Limit-* response headers exposed in the connector logs — they tell you exactly how close you are to each limit and when it resets.

For very large orgs (50,000+ users), consider:

• Splitting users and groups across two connectors (one with ImportUsers=true, ImportGroups=false and one inverse).
• Disabling membership reads on the user/group connector and adding a third connector dedicated to memberships.
• Filing an Okta support ticket to request raised rate limits if your import schedule genuinely cannot fit within the standard per-org budget.

Security model

• App-only auth — no user impersonation, no consent prompts. The connector authenticates as the API token’s owning admin, so audit log entries in Okta attribute the reads to that admin account.
• Outbound only — the connector calls https://<your-org>.okta.com. No inbound paths.
• Read-only in phase 1 — the connector never issues a write request. The token’s permissions also constrain what is possible regardless of what the connector attempts.
• Token in transit — the API token never leaves the IdentityMesh secret store unencrypted; the SSWS header value is composed in memory and discarded after each request.
• Logging — API tokens, secret values, and bearer headers are never written to logs. The connector logs page counts, watermark advances, and any rate-limit warnings, but not authentication material.

What’s deferred to phase 2

The following are not in phase 1 and will be added in a follow-up phase:

• Export / write-back — creating users, updating profile attributes, managing group membership, and deactivating accounts. In phase 1 an export against this connector fails with an explanatory message, so the engine surfaces the limitation cleanly rather than silently dropping changes.
• OAuth2 service apps (private-key JWT) — replaces static API tokens with a key-scoped, per-app credential pattern. Better audit trail and no token-inactivity expiry.
• System Log driven hard-delete detection — read /api/v1/logs?filter=eventType eq "user.lifecycle.delete" and emit Delete changes for users that have been purged from the directory. Closes the periodic-full-sync workaround documented above.
• App assignments — import which Okta apps each user is assigned to, plus the assignment metadata. Useful for certification campaigns.
• MFA factors — read each user’s enrolled factors (SMS, push, WebAuthn, etc.) for compliance reporting.
• Custom profile attributes — the extensible Okta profile schema. Phase 2 will add an opt-in flag to import every profile.* field, including custom attributes the operator has added through the Okta admin console.
• Group rules — the rule definitions that drive dynamic group membership. Useful for understanding why a user landed in a particular group.

Troubleshooting

401 Unauthorized on every page

• The API token has expired (30 days of inactivity) or been revoked. Generate a new token in Security → API → Tokens and update the secret store entry.
• The admin who created the token has been deactivated. Tokens inherit the creator’s lifecycle — recreate the token from an active admin account.

403 Forbidden on /api/v1/users or /api/v1/groups

• The token’s owning admin lacks read access to users or groups. Recreate the token from an admin role that holds the required read permissions (the built-in Read-Only Administrator role works).

Repeated Retry-After log entries

• See “Throttling and rate limits” above. Lower PageSize, split the connector, or stagger schedules.

Slow imports

• Disable ImportMemberships if you don’t yet need group-membership data in the mesh. Group-member reads dominate runtime on orgs with thousands of groups.
• Lower PageSize if the slowness coincides with Retry-After warnings — the perceived slowness is throttling, not request latency.

Users that were hard-deleted from Okta still appear in the mesh

• This is the documented lastUpdated gap. Trigger a Full-mode run to walk the entire user list and let the mesh reconcile.
• Schedule a recurring full sync (weekly is typical) so this reconciliation happens automatically.

Watermark “stuck” at an old timestamp

• The watermark column in the database stores the JSON wrapper {"u":"...","g":"..."}. Inspect it directly in SQL to confirm the current high-water value. If it looks wrong, you can edit it by hand (or trigger a Full run, which ignores it).

Cross-references

• secret-rotation.md — rotating the Okta API token on a 90-day cadence.
• secrets-and-dpapi.md — the default DPAPI-backed secret store used by the helper script.
• secrets-keyvault.md — pointing the connector at Azure Key Vault instead of DPAPI.
• secrets-vault.md — pointing the connector at HashiCorp Vault instead of DPAPI.
• connector-entra.md — the sister Entra ID connector. Run alongside Okta during an Okta → Entra migration; the merge behaviour in the mesh is governed by the join rules configured in the Admin UI.
• relay-agent.md — running this connector on a relay agent in a remote network instead of the central engine.