Okta

Prev Next

This guide will teach you how to set up the connector between Okta and Clarity Security.

Estimated time to complete: 20 minutes (v2 OAuth private key) or 10 minutes (v1 API token)

If you encounter any problems, please contact your support team or support@claritysecurity.io.

What the Connector Does

Clarity reads your Okta users, groups, applications (active apps only) and administrator role assignments, and can provision access back into Okta when provisioning is enabled for the application. Clarity never reads or changes passwords or MFA factors, and it does not create or delete groups or applications.

Supported Connector Capabilities

Below are capabilities supported by the connector at this time.

MethodSupported
Ability to Act as a Source of TruthYes
Provision UserYes
List Groups, Applications, and Admin RolesYes
Add User to Groups, Applications, and Admin RolesYes
Remove User from Groups, Applications, and Admin RolesYes
Deactivate and Reactivate UserYes
Delete UserYes

Choose a Connector Version

Clarity offers two ways to authenticate to Okta. You pick one in the Connector Version field when you add the application.

VersionHow Clarity authenticatesUse it when
v2 OAuth private key (recommended)An Okta API Services app using OAuth 2.0 client credentials with a private key. Tokens are short-lived, scoped, and not tied to a person.All new connections.
v1 API token (legacy)An Okta API token created by an admin. The token carries every permission that admin has and stops working if that admin's account is deactivated.Existing connections that have not moved to v2 yet.

Neither version shows an OAuth consent screen or redirects you to Okta. Both versions sync and provision the same data.

Before You Begin

To connect Okta and Clarity Security, you'll need the following before you begin:

  1. A Super Administrator in Okta for the one-time setup. For v2, Okta only shows the app's Okta API Scopes and Admin Roles tabs to Super Administrators. The connector itself does not need Super Administrator afterwards.
  2. Admin access within your Clarity Security tenant.
    • Note: If you are a full admin in Clarity Security and get a permission error when trying to add a new application, reach out to support@claritysecurity.io.
  3. Your Okta org domain. See Your Okta Org Domain at the end of this article.

Option A: v2 OAuth Private Key (Recommended)

Step 1: Create an API Services app in Okta

  1. In the Okta Admin Console, go to Applications > Applications > Create App Integration.
  2. Select API Services and click Next.
  3. Name it Clarity Security and click Save.
  4. Copy the Client ID from the top of the app's General tab. You will enter it in Clarity in Step 5.

Step 2: Switch the app to a private key

  1. On the General tab, find Client Credentials and click Edit.
  2. Set Client authentication to Public key / Private key.
  3. Under Public keys, choose Save keys in Okta, then Add key > Generate new key.
  4. Copy the private key now. Okta shows it only once. Either format works in Clarity: the PEM tab (starts with -----BEGIN PRIVATE KEY-----) or the JWK JSON Okta shows by default. Copy the whole value, including the BEGIN and END lines for PEM.
  5. Click Done, then Save. Accept the warning that the client secret will be removed.
  6. Copy the key's KID from the Public keys list.

Leave Require Demonstrating Proof of Possession (DPoP) header in token requests at whatever Okta set. Clarity works either way.

Step 3: Grant the Okta API scopes

On the app's Okta API Scopes tab, click Grant for each scope Clarity will use.

Always (sync)Also when provisioning is enabled
okta.users.readokta.users.manage
okta.groups.readokta.groups.manage
okta.apps.readokta.apps.manage
okta.roles.readokta.roles.manage

If provisioning is enabled for the Clarity application, grant all eight scopes. Clarity requests the manage scopes whenever provisioning is on, and Okta refuses the whole token request if any requested scope is missing. The sync fails, not just the write-back.

Step 4: Assign the app an admin role

Scopes alone are not enough. Okta also checks the app's own admin role on every API call. Without one, Clarity gets a token but every call returns 403.

Recommended: a least-privilege custom role for reading.

  1. Go to Security > Administrators > Roles > Create new role. Name it Clarity Readand add these permissions:
    • User: View users and their details
    • Group: View groups and their details
    • Application: View applications and their details
    • Identity and Access Management: View roles, resources, and admin assignments
  2. Go to Security > Administrators > Resources > Create new resource set and add All users, All groups, All applications, and All Identity and Access Management resources.
  3. Back on the app, open the Admin Roles tab, click Edit assignments, and assign Clarity Read with that resource set.

If Clarity will provision access, add a second custom role for the writes and assign it to the app alongside Clarity Read, on the same resource set:

  1. Go to Security > Administrators > Roles > Create new role. Name it Clarity LCMand add these permissions:
    • User: Create users
    • User: Edit users' profile attributes
    • User: Edit users' lifecycle states
    • User: Edit users' group membership
    • User: Edit users' application assignments
    • Group: Manage groups
    • Application: Edit application's user and group assignments
  2. On the app's Admin Roles tab, click Edit assignments and add Clarity LCM with the resource set from above.

This role does not include deleting users or assigning admin roles. Those two actions still need the Super Administrator role on the app.

A custom role cannot change Super Administrators. Okta only lets a Super Administrator manage another Super Administrator, so any write that targets a Super Admin user, including adding or removing them from a group, returns 403 even though the same write succeeds for everyone else. Either assign the app the Super Administrator role, or manage Super Admin accounts in Okta directly.

Step 5: Log in to Clarity

Login to your Clarity Security tenant with admin access.

Step 6: Click on Applications > Marketplace

Navigate to the applications section and then click "Marketplace".

Clarity Applications > Marketplace

Step 7: Click Connect

Click Connect on the Okta option from the marketplace to begin configuring your application connector.

Clarity Application Marketplace - Okta Connector Listing

Step 8: Connect App

Set Connector Version to v2 OAuth private key, then fill in the credentials. Details for fields common to all applications can be found in the following article: Common App Configuration Steps.

Clarity fieldWhat to enterWhere it comes from
Okta domainYour Okta org host, for example acme.okta.com. No https:// needed.The address bar of your Okta Admin Console. See Your Okta Org Domain below.
Client IDThe app's client ID. Starts with 0oa.Step 1
Key ID (KID)The key's KID.Step 2, the Public keys list
Private keyThe whole private key, PEM or JWK.Step 2. Shown once in Okta, masked in Clarity after saving.

All four fields are required. Click Test Credentials. Clarity exchanges the key for a token and reads one group from your org. A success means the domain, client, key and admin role are all working.

Then continue with App Settings, User Settings and Save below.

Option B: v1 API Token (Legacy)

An Okta API token inherits the permissions of the account that created it and is invalidated if that account is later deactivated. This is the single most common cause of a connector that worked for months and then began failing. Create the token from a dedicated service account, not a named person's account, or use v2 instead.

Step 1: Create a service account to own the token

  1. In the Okta Admin Console, go to Directory > People > Add person.
  2. Create an account that is not tied to an individual employee, for example svc-clarity@yourcompany.com.
  3. Activate the account.

Step 2: Grant the account an administrator role

  1. Go to Security > Administrators > Add administrator.
  2. Select the service account from Step 1.
  3. Assign a role:
    • Read-only Administrator is enough to read users, groups, apps and roles.
    • Super Administrator is needed if Clarity will provision access back into Okta.

Step 3: Create the API token

  1. Sign in to the Okta Admin Console as the service account from Step 1. The token belongs to whoever is signed in when it is created.
  2. Go to Security > API > Tokens > Create Token.
  3. Give the token a descriptive name, such as Clarity Security Connector, then click Create Token.
  4. Copy the token value into a secure and retrievable location. Okta will not show this token again. If it is lost you must create a new one.

Okta Landing Page - Security > API

Create Token - Copy the Value

Note: Okta API tokens expire after 30 days without use. Once connected, Clarity's regular syncs keep the token active, but a token created well before onboarding finishes can expire before its first use.

Step 4: Connect App in Clarity

Log in to Clarity, go to Applications > Marketplace, click Connect on Okta, set Connector Version to v1 API token, and fill in:

Clarity fieldWhat to enter
okta_domainYour Okta org host, for example acme.okta.com (a bare acme also works). See Your Okta Org Domain below.
api_tokenThe token value from Step 3. Paste the value only, without any SSWS prefix.

Both fields are required. Click Test Credentials, then continue with App Settings, User Settings and Save below.

Finish the Application Setup (both versions)

App Settings

Complete the App Settings form. Details for each field can be found in the following article: Common App Configuration Steps.

Configure App Step 2 - App Settings

User Settings

Complete the User Settings form. Details for each field can be found in the following article: Common App Configuration Steps.

Configure App Step 3 - User Settings

Validate Your Selections and Save

Save
Clicking the Save button will trigger the first full sync for your application (even if you selected Manual syncing). This includes Service Users, Entitlements, Service User Entitlements and Service User Attributes.

Your Okta Org Domain

This is the hostname you use to reach your Okta org, without https://.

Your org typeValue to use
Standard commercial orgacme.okta.com, or just acme
Preview / sandbox orgacme.oktapreview.com
EMEA cellacme.okta-emea.com
Custom domainid.yourcompany.com

A bare subdomain such as acme is treated as acme.okta.com. A pasted URL such as https://acme.okta.com/ is reduced to its host. If you paste the Admin Console address (acme-admin.okta.com), Clarity uses the org host acme.okta.com instead. Custom domains are never rewritten.

Use the org the credentials were created in. Credentials from a preview org are rejected by the production org and vice versa.

Troubleshooting

SymptomLikely causeFix
invalid_client (v2)Okta rejected the signed client assertion.Check, in order: the Client ID belongs to this org; the Key ID matches the key you pasted (a regenerated key has a new KID); you pasted the private key, not the public one; Client authentication is set to Public key / Private key.
invalid_scope (v2)Clarity asked for a scope the app has not been granted.Grant the missing scopes on the Okta API Scopes tab. With provisioning enabled, all eight are required.
Test passes but the sync reports 403 or skips admin roles (v2)The app has no admin role, or its role is too narrow.Assign a role on the app's Admin Roles tab (Step 4). When the role cannot read admin roles, Clarity skips that part of the sync and marks it degraded rather than removing admin-role entitlements it can no longer see.
Provisioning returns 403 for one user but works for othersThe target user is a Super Administrator and the app holds a custom role.Okta blocks custom-role admins from changing Super Admins. Assign the app Super Administrator or manage those accounts in Okta directly. Clarity currently logs this as "Authentication failed" even though the token itself was accepted.
I can't see the Okta API Scopes or Admin Roles tab (v2)You are not signed in as a Super Administrator.Ask a Super Administrator to complete Steps 3 and 4.
401 E0000011 Invalid token provided (v1)The account that created the token was deactivated, the token was revoked or expired after 30 days unused, the token came from a different org than the domain entered, or the value was mis-pasted.Go to Security > API > Tokens, find the token and its creator, and check that user in Directory > People. Mint a new token from an active service account, or move to v2.
403 on some endpoints but the connection test passes (v1)The token's admin role is too narrow. The test only reads groups.Grant a broader role to the service account (Option B, Step 2).
cURL error 6: Could not resolve host or cURL error 60The Okta domain is not a hostname Clarity can reach.Check for a typo in the cell suffix. Enter the host only, for example acme.oktapreview.com.
Sync completes but entitlements are emptyThe admin role cannot see applications or admin roles.Retry with Read-only Administrator to confirm, then narrow the role again.

Good to Know

  • Every Okta account in Clarity carries Okta's own user status (for example ACTIVE, SUSPENDED, DEPROVISIONED) and the date it last changed, as attributes. Clarity treats SUSPENDED and DEPROVISIONED accounts as inactive and every other status as active. These attributes alone do not trigger any lifecycle workflow.
  • Only active Okta applications are read. Inactive apps and their assignments do not appear in Clarity.
  • Clarity polls Okta on its sync schedule. It does not register Okta event hooks.
  • Clarity does not read Okta policies, authorization servers or sign-on rules.
  • To use Okta to sign in to Clarity itself, see Using Okta for SSO. SSO does not require this connector.

Need Help?

If you have any problems, contact your customer success team. You can also get in touch with our general support via email, open a support ticket. Our general support team is available Monday - Friday from 8:00 AM - 6:30 PM CST.