Skip to main content
This article consolidates everything needed to set up Okta with Lumos: connecting the integration (API token or OAuth API Services), the required roles and scopes, putting Lumos behind Okta SSO, SCIM user provisioning into Lumos, and Okta webhooks for live group and application updates.

​
After this article

You’ll be able to connect the Okta integration to Lumos, put Lumos behind Okta SSO, enable SCIM and webhook-based live updates, and resolve common connection issues.

​
Capabilities

Updating profile attributes. Workflows that update an Okta user’s profile can both set and clear attributes. A cleared attribute (for example Secondary Email) is removed from the Okta profile rather than left at its previous value.

​
Activity Tracking

Status: Supported. Lumos reads Okta System Log entries (okta.logs.read / /api/v1/logs) to sync user last-activity data. This requires a standard admin role (custom admin roles cannot read System Logs).

​
Required plan and roles

There’s no minimum Lumos plan or subscription required to connect the Okta integration. On the Okta side, at a bare minimum you need the Universal Directory and Single Sign On SKUs to integrate Okta with Lumos. To automate provisioning and deprovisioning workflows to the fullest extent (via SCIM), also purchase the Lifecycle Management SKU. Super Administrator is recommended for full functionality, with options to configure with restricted access. A Read-Only connection is not supported for this integration.

​
(API Token) Required roles and permissions

An Okta API token inherits the permissions of the Okta user account that creates it. The token gets the permissions of the user who is logged in at creation time. Lumos recommends creating a dedicated Okta service-account user to connect the integration to Lumos, so permissions aren’t tied to a specific employee (a personal token breaks when that employee’s role changes or they leave). Using a Super Administrator role for the integration user gets you up and running fastest. Restricting access without Super Admin. To unlock the full functionality of Lumos without Super Administrator, the integration user needs the following standard Okta roles:
  • Group Membership Administrator: Can administer all groups: Manage users, their profiles, and their credentials
    • You can scope to individual groups after selecting this role, but you’ll need to maintain the list.
  • Application Administrator: Can administer all applications: View and manage user permissions in an application
    • You can scope to individual apps, but you’ll need to maintain the list. This is required to sync custom attributes.
  • Report Administrator
Alternatively, create a custom Okta admin role (with a matching Resource Set) granting:
  • User permissions: Edit users’ lifecycle states, View users and their details, Edit users’ application assignments, Edit users’ group membership
  • Group permissions: View groups and their details, Manage group membership
  • App permissions: Manage applications, View applications and their details, Edit application’s user assignments
  • The user must also be paired with Application Administrator, API Access Management Admin, or Org Admin in order to fetch custom user attributes.
Custom role limitations (Okta platform limitations):
  • Custom admin roles cannot modify group memberships of Okta users who are Super Administrators. Any attempt to add or remove Super Administrators from Okta groups via Lumos will fail with a custom admin role.
  • A Super Administrator role is needed to list Admin roles in Okta, required if you want to view Okta admin roles in Lumos (e.g. during an Access Review). See Using Lumos for Access Reviews.
  • Custom admin roles cannot access Okta System Logs, even when the okta.logs.read scope is granted. Log-based features (user activity/last login) require a standard admin role.

​
(OAuth API Services) required scopes

The API Services version of the integration authenticates with an OAuth app instead of a user token. The person completing the connection must have the authorization (role + permissions) to grant the requested scopes. For full syncing and provisioning capabilities, Super Administrator is required. The same standard-role or custom-role alternatives above apply if you want to restrict access. When listing scopes for the integration app, separate each scope with an empty space (not a comma). For more context, see the Okta OAuth 2.0 scopes documentation.

​
Read-only access vs provisioning

Is read-only possible? No. A read-only connection is not supported for this integration, and the OAuth version’s okta.apps.manage scope has no read-only equivalent, so every connection carries write access to applications at minimum. You can narrow the user and group scopes (okta.users.read in place of okta.users.manage, okta.groups.read in place of okta.groups.manage), but that still leaves okta.apps.manage in the grant. What full provisioning requires. Super Administrator gets you full functionality fastest. To restrict access without Super Administrator, pair the standard roles Group Membership Administrator, Application Administrator, and Report Administrator (or an equivalent custom admin role granting the documented user, group, and app permissions), then follow the steps below. The OAuth API Services method needs the same admin role plus the scopes listed above, with okta.apps.manage required and no read-only substitute. Watch out for. Custom admin roles cannot modify group memberships of Super Administrators and cannot list Okta admin roles, both of which require Super Administrator. Reducing the integration user’s role without keeping an org-wide read scope can silently narrow which users Lumos sees. Connecting more than one Okta tenant breaks SCIM provisioning into Lumos, so there is no supported way to run a separate read-only Okta connection alongside a provisioning one.

​
Instructions

​
Option A: connect with an API token

In Okta
  1. (Recommended) Create a dedicated service-account user in Okta and assign it an admin role (Super Administrator, or the restricted role combination above).
  2. Log in as the user whose permissions the token should inherit and create an API token. In production (Admin Console) go to Security → API → Tokens. In a sandbox (Developer Console) select Tokens from the API menu. Save the token value, it is only shown once.
In Lumos
  1. Find the Okta card in your Lumos integrations (Reconnect or add new).
  2. In the Domain field, enter your Okta domain exactly in the format [SUBDOMAIN].okta.com. Do not include the https:// prefix. Your value should look like example.okta.com (or example.oktapreview.com for an Okta sandbox).
  3. In the API key field, enter your API token from Okta.
  4. Click Connect Okta.

​
Option B: connect with OAuth API Services

  1. In Lumos, select the API Services version of the Okta integration (Integration Version dropdown) and click Get Key to obtain the public key Lumos provides.
  2. In Okta, create an API Services app integration and add the public key. Ensure Require Demonstrating Proof of Possession (DPoP) is unchecked.
  3. On the app’s Okta API Scopes tab, grant the scopes listed above (this tab is separate from the OAuth Scopes section, and scopes not granted here cause consent_required errors).
  4. Assign the app the Super Administrator admin role (for full syncing and provisioning).
  5. Paste the app’s Client ID back into Lumos and complete the connection.

​
Putting Lumos behind Okta (SSO tile)

You’ll need an ACS URL and SP Entity ID from Lumos. Contact your Lumos representative to generate them.
  1. Log in to Okta, open the admin dashboard, and select Applications.
  2. Create a new SAML 2.0 application (a Lumos logo for the tile is available from Lumos support).
  3. Obtain the Single sign on URL (ACS URL) and Audience URI (SP Entity ID) from the Lumos team.
  4. Complete the SAML app configuration with those values and add the attribute statements:
  1. Finish the application setup form.
  2. On the Assignments tab, assign the people and/or groups allowed to log into Lumos.
  3. On the Sign On tab, copy the Metadata URL and send it to Lumos support.
  4. Once Lumos confirms SSO is configured, verify you can log in from the Okta tile or the Lumos login page.

​
Using SCIM for user provisioning into Lumos

SCIM makes users created in Okta automatically and instantly available in Lumos, with no waiting for a full sync. Requirements:
  • Permission in Okta to edit your Lumos tile
  • Organization Admin role in Lumos
  • Okta integrated in Lumos and set as your first User Source
  • Only one Okta tenant integrated in Lumos (SCIM always fails with multiple tenants)
  • Each user’s Okta login/username must exactly match their email address, or SCIM provisioning fails for that user
Supported features (To App): Create Users, Update User Attributes, Deactivate Users. Attribute mappings: userName, givenName, familyName, email, title. Manager and custom attribute changes are not supported, and Push Groups is not supported. Steps:
  1. In Lumos, go to Settings → API Tokens and generate a new API token (name it clearly for SCIM). Do not share it.
  2. In the Okta Admin portal, open your Lumos app: General → App Settings → Edit, set Provisioning to SCIM, and Save.
  3. Under Provisioning → Integration → Edit, enter:
    • SCIM connector base URL: https://api.lumos.com/scim/v2
    • Unique identifier field for users: userName
    • Supported provisioning actions: “Push New Users” and “Push Profile Updates”
    • Authentication Mode: HTTP Header, paste your Lumos API token in the “Bearer” field
  4. Click Test Connector Configuration and verify “Create Users” and “Update User Attributes” are healthy, then Save.
  5. Under Provisioning → Settings → To App → Edit, enable Create Users, Update User Attributes, and Deactivate Users, then Save.
  6. Provision existing assigned users via the Provision User action.
  7. Verify by assigning a new Okta user to Lumos. They should appear on your Lumos Users page.

​
Using Okta webhooks for live group and application updates

Okta event hooks make group, group-membership, and application changes appear in Lumos in about 10 seconds instead of waiting for the next sync. Requirements: permission in Okta to edit your Lumos tile, Organization Admin in Lumos, and Okta already integrated in Lumos. Supported group events: group created, updated, and deleted; user added to and removed from a group; application added to, removed from, and updated in a group. Supported application events: application created, updated, activated, and deactivated. An app created in Okta is added to Lumos as soon as the event arrives, so you can reference it in Lumos (for example from a Terraform-managed Okta org) without waiting for the next app scan. An app deactivated in Okta is marked inactive in Lumos and removed from the AppStore.
  1. In Lumos, go to Settings → API Tokens and generate a new API token.
  2. In Okta Admin, go to Workflows → Event Hooks → Create Event Hook and set:
    • Name: any name
    • URL: https://api.lumos.com/events/okta
    • Authentication field: Authorization
    • Authentication secret: Bearer <your Lumos API token>
    • Subscribe to events: Create Okta group, Delete Okta group, Okta group profile updated, User added to group, User removed from group, Add assigned application to group, Remove assigned application from group, Update assigned application in group, and the four application lifecycle events (application.lifecycle.create, application.lifecycle.update, application.lifecycle.activate, application.lifecycle.deactivate)
  3. Click Save & Continue, then Verify. A success message confirms the hook is live.
Limitation: Lumos only syncs group memberships in real time for Okta users already discovered by Lumos. A user recently added to Okta may take up to 24 hours to appear.

​
API Endpoints Used

​
Troubleshooting

​
I can’t connect the Okta integration

  • Make sure the URL in the Domain field is exactly in the format subdomain.okta.com. It will fail if you include https://.
  • If the domain is correct, make sure your API key from Okta doesn’t contain any typos.

​
I only see one user in the Accounts tab

  • The Okta integration user likely does not have access to view other users. Check the permissions of your Okta integration user and make sure there are no restrictions on its ability to view and manage users.

​
The connection broke after an admin’s role changed or they left

  • API tokens inherit the creating user’s permissions. If that user’s role is reduced or removed, syncs fail with invalid-credential errors. Reconnect using a dedicated service account or, preferably, the OAuth API Services method (an app-level credential not tied to any individual). Resyncing alone does not recover a broken connection, so re-enter credentials and click Reconnect.
  • The scopes were not granted on the API Services app’s Okta API Scopes tab (distinct from the OAuth Scopes section). Grant them there and reconnect.

​
Custom attributes aren’t syncing

  • Fetching custom attributes requires the connecting user/app to be paired with Application Administrator, API Access Management Admin, or Org Admin. Insufficient access surfaces as HTTP 403 (Okta error E0000006) on the user schema endpoint.

​
Okta API rate limit warnings or violations

  • Lumos syncs once per day and throttles itself to ~50% of its per-token rate limit (90% for the /api/v1/logs endpoint). Because a default Okta token is capped at 50% of the per-tenant limit, Lumos uses roughly 25% of your tenant limit. Violations occur when other tokens consume the rest: keep the sum of all token rate limits at or below 100% of the per-tenant limit, restrict other heavy-usage tokens, or lower the Lumos token’s limit (this slows the sync). Okta’s rate-limit notifications warn at 60% by default.

​
SCIM: “Multiple Okta integrations found”

  • You have multiple Okta tenants connected in Lumos. SCIM into Lumos requires exactly one Okta tenant.

​
SCIM: a user fails to provision

  • SCIM provisioning fails when the user’s Okta login/username doesn’t exactly match their email address. Only userName, givenName, familyName, email, and title attribute mappings are supported, and Push Groups is not supported.
A user is missing from an Access Review (UAR). A user can drop from a UAR if their account was Suspended at the snapshot time, since the scope excludes suspended accounts. Lumos shows the status Okta returns — check the Okta System Log to see what toggled the account around the snapshot. Re-pointing an app to a different Okta integration. To move an app from one integration to another, first unmerge the old integration app from the Okta app, then merge the new integration app with the Okta app. Merging fails if the old (now disconnected) integration is still merged. Can I force a sync for a single user? Yes — after updating a user’s attributes in Okta you don’t have to run a full sync or wait for the overnight run; refresh that individual account from its record in Lumos so only that user re-syncs.

​
Sync started failing after you reduced the integration user’s role

  • Moving the integration user from Super Administrator to a narrower set of admin roles can leave the account without the permissions the account sync needs. The failure surfaces as a generic Insufficient permissions or Credentials are not valid for this integration error that does not name the missing permission.
  • Restore the sync by reconnecting with credentials that carry the full documented permission set (see (API Token) Required roles and permissions above), or temporarily with Super Administrator, and then narrow the role again once syncs are healthy.
  • Scoping matters as much as the role. Application Administrator scoped to a single app means Lumos only sees that app. If Okta is your source of truth, pair the scoped write roles with an org-wide (unscoped) custom role granting View users and their details, View groups and their details, and View applications and their details, so Lumos keeps full read coverage. Narrowing the visible user list to the members of one app can hide users who don’t have access to that app yet.
  • Before narrowing the role, confirm you don’t need the two functions that require Super Administrator: listing Okta admin roles, and changing group membership for users who are themselves Super Administrators.

​
Can I use two Okta integrations, one read-only and one for writes?

  • No. Connect a single Okta tenant. Connecting more than one Okta integration makes SCIM provisioning into Lumos fail with “Multiple Okta integrations found”.
  • A single scoped connection already achieves least privilege: org-wide read visibility plus write access limited to the specific apps and groups you choose, using Application Administrator scoped to those apps, Group Membership Administrator scoped to those groups, and Report Administrator. On the OAuth version, okta.users.manage and okta.groups.manage can be swapped for their .read equivalents where you don’t need writes.

​
A failed Okta sync didn’t retry

  • Lumos does not automatically re-run a failed full Okta sync. The next scheduled daily sync picks it back up, or you can trigger a manual sync yourself.
  • A full sync that is still running blocks the next scheduled full sync from starting, so a run that stays active longer than usual can delay the following days’ syncs.
  • There is no self-serve setting to configure a sync timeout. Sync run limits are managed internally. If a run looks stuck well beyond its normal duration, contact Lumos support to have the run cleared.

​
A new app I added in Okta isn’t showing up in Lumos

  • If your event hook subscribes to the application lifecycle events (see Using Okta webhooks for live group and application updates above), a new app reaches Lumos within seconds of being created. Otherwise, trigger the app scan:
  • Trigger the app scan instead of waiting: go to the AppStore, click Add App to AppStore, and in the pop-up click Sync Apps. This runs against Okta and usually completes in about 5 minutes. It also runs on its own roughly every 4 days.
  • To also pull in the app’s metadata, provisioning options, and Okta assignment groups, open Advanced Settings for the newly added app and click Sync App Data at the top. This takes roughly 10 to 20 minutes.
  • The app won’t surface at all unless at least one user is assigned to it in Okta. Likewise, an Okta group only appears on an app’s Permissions tab once at least one user is assigned through that group.

​
Getting Okta group changes into Lumos without waiting for the daily sync

  • If you create or update groups in Okta programmatically and need to reference them in Lumos right away, set up Okta event hooks (see Using Okta webhooks for live group and application updates above). Group and group-membership changes then reach Lumos in about 10 seconds instead of waiting for the next sync.
  • For newly created users, SCIM provisioning into Lumos makes the user available immediately rather than waiting up to a day for discovery (see Using SCIM for user provisioning into Lumos above).

​
I can’t match accounts on the Okta user ID or on employeeNumber

  • An identity matching rule has two sides, and each side is populated by a different pipeline. That’s why an attribute can be selectable on one side but not the other.
  • Identity field (right side): the identity attributes you configure, mapped from your sources of truth. An Okta attribute such as employeeNumber can be mapped here as a custom field under Settings → Source of Truth → Custom Fields, after which it becomes selectable in Identity Matching.
  • Account field (left side): the account exactly as that app’s connector discovered it. This is the standard field set (email, username, integration_specific_user_id, given_name, family_name, full_name, raw_identity_type, normalized_identity_type) plus whatever custom attributes the connector returns. Custom account attributes use the form account.custom_attributes["<exact attribute name>"], so an expression like account.custom_Employee_Number is rejected as an invalid property.
  • For Okta accounts, the synced account custom attributes are a fixed set: title, division, department, start date, the Okta manager fields, and the source account created date. employeeNumber is not in that set today, so there is no Okta account expression that resolves to it. This is a known limitation.
  • The Okta user ID can’t be used as the match key against another app’s accounts unless that app’s connector itself returns the Okta ID on the account. Provisioning a value out to an app is a separate path from reading it back in during discovery, so an attribute Lumos writes into an app is not automatically matchable.
  • Email remains the reliable match key in the meantime.

​
A user I removed in Okta still shows as Active on an app

  • If Lumos discovers the same account both through Okta and through that app’s own direct integration, the two records are consolidated by source priority, and a direct app connector outranks the Okta-sourced record. The Okta-sourced record can correctly read Suspended while the displayed status stays Active, because the direct connector still reports the account as active.
  • Removing a user in Okta, or removing them from one product within an app, doesn’t necessarily deactivate their underlying account in that app. Deactivate or delete the account in the app itself, or deprovision it through Lumos, and the status updates on that app’s next sync.

​
Granting an Okta admin role through Lumos fails with a credentials error

  • Okta only allows an API-connected account to assign administrator roles up to its own level of privilege. An integration connected with a narrower admin role (for example Group Membership Administrator or Application Administrator) can still handle most provisioning work, but it can’t grant the Super Administrator role.
  • Confirm which admin role the connecting user or API Services app currently holds. If it isn’t Super Administrator, reconnect with Super Administrator credentials (or an API token created by a Super Administrator).
  • An Okta preview/sandbox org and your production Okta org are separate connections in Lumos. Correcting the role on one does not affect the other, so review each connection you rely on.
  • If requests still fail with Credentials are not valid for this integration after Super Administrator is confirmed on the correct org, contact Lumos Support with the timestamp of a test request so the logs can be reviewed.

​
I added a scope to the API Services app but syncs still fail with 403

  • Open the Okta card and click Reconnect, entering the client configuration again. Scopes added in Okta after the initial connection only take effect once Lumos requests a new token, which a reconnect now forces.

​
A group membership change failed because Okta refused it

  • When Okta rejects adding or removing a user from a group, the failed task shows that Okta refused the change and the reason Okta returned. Common causes are a custom admin role that is not scoped to the group, or changing the membership of a Super Administrator.