# Okta Connecting Okta gives SureCloud read access to your Okta tenant's users, groups, applications, authentication policies, and administrator role assignments. SureCloud monitors MFA enrolment at the per-user level, verifies that sign-on policies require strong authentication factors, audits administrator role assignments for excessive privilege, and collects system log events to provide an audit trail of authentication and administrative activity. This gives continuous evidence that your identity provider is configured to enforce access controls as required. {% hint style="info" %} SureCloud connects to Okta using OAuth 2.0 (OIDC) where supported by your Okta edition, or via a scoped API token for tenants that do not support OAuth service apps. The preferred method is OAuth 2.0 — it avoids the need to store long-lived API tokens and allows fine-grained scope control. {% endhint %} ## Authentication and setup {% tabs %} {% tab title="OAuth 2.0 (recommended)" %} {% stepper %} {% step %} #### Create an OAuth 2.0 service app in Okta In your Okta Admin Console, navigate to **Applications → Applications → Create App Integration** and select **API Services**. * **App name**: `SureCloud CCM` * Click **Save**. Note the **Client ID** from the app's **General** tab. {% endstep %} {% step %} #### Generate a client secret On the app's **General** tab, under **Client Credentials**, click **Edit** and set the **Client authentication** method to **Client secret**. Click **Save**, then click **Generate new secret** and copy the value immediately. {% endstep %} {% step %} #### Assign OAuth scopes On the app's **Okta API Scopes** tab, grant the following scopes: | Scope | Purpose | | -------------------- | ----------------------------------------------- | | `okta.users.read` | Enumerate users and their MFA factor enrolment | | `okta.groups.read` | Read group memberships and assignments | | `okta.apps.read` | List application assignments and configurations | | `okta.policies.read` | Read authentication and password policies | | `okta.roles.read` | Enumerate administrator role assignments | | `okta.logs.read` | Read system log events | Click **Save**. {% endstep %} {% step %} #### Enter credentials in SureCloud In SureCloud, navigate to **Integrations → Okta → Connect** and provide: * **Okta domain** (e.g. `yourcompany.okta.com` or `yourcompany.okta-emea.com`) * **Client ID** * **Client Secret** Click **Test Connection**, then **Save**. {% endstep %} {% endstepper %} {% endtab %} {% endtabs %} ## Endpoints | API Call | Use Case | | ---------------------------------------- | ----------------------------------------------------------------------------- | | `GET /api/v1/users` | Enumerate all users; detect deprovisioned, suspended, and locked-out accounts | | `GET /api/v1/users/{id}/factors` | Retrieve enrolled MFA factors and enrolment status per user | | `GET /api/v1/users/{id}/roles` | List administrator roles assigned directly to each user | | `GET /api/v1/groups` | Enumerate all groups and their membership counts | | `GET /api/v1/groups/{id}/users` | List members of each group | | `GET /api/v1/apps` | List all applications configured in Okta | | `GET /api/v1/apps/{id}/users` | Enumerate users assigned to each application | | `GET /api/v1/policies?type=OKTA_SIGN_ON` | Read sign-on policies and their rule configurations | | `GET /api/v1/policies?type=PASSWORD` | Read password policies for each group/application | | `GET /api/v1/roles` | List all administrator roles and their permissions | | `GET /api/v1/logs` | Retrieve system log events for authentication and administrative activity | ## Pagination The Okta API uses cursor-based pagination via a `next` URL in the `Link` response header. SureCloud follows the `next` link in successive requests until no `next` link is present. ```http Link: ; rel="next", ; rel="self" ``` {% hint style="info" %} SureCloud requests up to 200 objects per page using the `limit=200` query parameter, which is the maximum permitted by the Okta API for most endpoints. {% endhint %} ## Required permissions For OAuth 2.0, grant the scopes listed in the setup steps above on the API Services app. For API token, the generating account must hold the **Read-Only Administrator** role. The Read-Only Administrator role grants read access to users, groups, applications, policies, and logs. It does not grant access to credentials, secrets, or write operations. ## Troubleshooting
MFA factor data is missing for users who have MFA enrolled The `okta.users.read` scope (OAuth) or Read-Only Administrator role (API token) is required to call `/api/v1/users/{id}/factors`. If factor data is missing, confirm the scope is granted on the OAuth service app and that admin consent has been applied. For API token connections, confirm the service account has the **Read-Only Administrator** role — non-admin accounts cannot call the factors endpoint across all users.
System log events are not appearing or show a large gap Okta retains system log events for **90 days** on most editions (longer on some enterprise plans). SureCloud collects events within a rolling window on each polling cycle. If SureCloud's connection was interrupted for more than 90 days, events from the gap cannot be recovered. Log collection resumes from the current time after a connection interruption. Verify the connection status in **SureCloud → Integrations → Okta**.
Authentication policy rules are not appearing Authentication policies require the `okta.policies.read` scope. For API token connections, the Read-Only Administrator role includes policy read access. If policies are missing, confirm the scope is granted (OAuth) or the service account role is correctly assigned (API token), then trigger a manual refresh from **SureCloud → Integrations → Okta → Edit Connection**.
Connection fails after an Okta token rotation If the API token used by SureCloud is rotated or deactivated in Okta (for example, when the service account password changes or the token is manually revoked), SureCloud will lose access. Generate a new token from the `surecloud-api` service account in **Okta → Security → API → Tokens**, then update it in **SureCloud → Integrations → Okta → Edit Connection → API Token**.
Okta Users API reference Okta OAuth 2.0 service app guide --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/okta.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.