Connect Okta to Simpplr

Overview

Before Simpplr can sync users, groups, or apps from Okta, you need to connect your Okta org. This article covers both connection methods and how to verify the connection. Once connected, see Sync users and attributes with Okta to choose what syncs.

Before you begin

• Okta SSO with Simpplr must already be set up.

• You must be a Super Admin in your Okta org to create the connection.

• You must be an App Manager in Simpplr

Choose a connection method

Connect with Okta Client OAuth

This setup moves between the Okta Admin Console and Simpplr, so follow the steps in order.

Recommended: Connect with OAuth 2.0 client credentials instead of an API token. A static API token never expires and carries full admin access, so it's a standing security risk if exposed. With OAuth, you don't hand over a long-lived token at all, Simpplr gets only scoped, read-only access that rotates automatically.

Step 1: Create a new App Integration in Okta

1. In the Okta Admin Console, go to Applications > Applications > Create App Integration.

2. Select API Services, then click Next.

3. Enter a name (for example, Simpplr Sync) and click Save

   

4. On the app's General tab, under General Settings, click Edit and make sure Proof of possession is turned off (clear the Require Demonstrating Proof of Possession (DPoP) header in token requests checkbox), then Save.

   

5. Confirm Grant type is set to Client Credentials.

6. Copy the Client ID - you'll need it in Step 4.

7. Note your Okta domain (for example, yourcompany.okta.com). You can also copy this from your browser's address bar while signed in to the Okta Console.

You will need the Client ID and Okta domain to create the connection in your Simpplr instance.

Step 2: Assign the admin role

1. On your API Services app, open the Admin roles tab (in the row of tabs near the top of the app page, alongside General, Okta API Scopes, and others).

2. Click Edit assignments. The role assignment panel opens.

3. Open the Role dropdown and select Read-only Administrator.

4. Click Save assignment (or Save) to apply it. The role now appears in the list of assigned roles.

   Note: Without this role, the sync fails with a permission error even after the connection is set up.

Step 3: Grant API scopes

1. Return to your API Services app. If you navigated away, go to Applications > Applications and select the app you created in Step 1.

2. Open the Okta API Scopes tab (in the same row of tabs as General and Admin roles).

3. Find each scope below and click Grant next to it:

4. Confirm each scope now shows as Granted in the list.

Step 4: Start the connection in Simpplr

1. In your Simpplr’s instance, go to Manage > Application > People > Provision & sync users.

2. Select the Scheduled source to Okta.

3. Enter the Okta Link and Client ID from that you copied earlier from Step 1, then click Save.

   

4. Click Generate key. Simpplr generates a token - copy it.

   

Step 5: Add the public key in Okta

1. Return to your API Services app in Okta (General tab) and click Edit under Client Credentials.

2. For Client authentication, select Public key / private key (instead of Client secret).

3. In the PUBLIC KEYS section, click Add key, paste the public key you copied from Simpplr, then click Done.

4. Click Save.

   

Step 6: Verify the connection in Simpplr

1. Back in Simpplr, click Test (below the Generate Token section).

2. If verification succeeds, the connection is active and ready to sync.

   Alert:

   If verification fails, verify the domain, Client ID, assigned role, and granted scopes. Then generate a new key in Simpplr and repeat Step 5.

Migrate from an API token to OAuth

If you are already using Okta API token, switch to Okta Client OAuth to keep syncing.

1. Follow Option A - Connect with Okta Client OAuth above. Your existing sync settings and field mappings are preserved.

2. After verification succeeds, the connection uses OAuth automatically.

3. (Optional) In Okta, revoke the old API token under Security > API > Tokens.

Troubleshooting

Connection verification fails: Okta domain or Client ID is incorrect

• What happened: The Okta domain or Client ID entered in Simpplr does not match the values from your Okta API Services app. A typo or trailing space can cause verification to fail.

• What to do: Open your API Services app in Okta and go to the General tab. Re-check both values, copy them carefully, and update them in Simpplr under Manage > Application > People > Provision & sync users. Click Test to verify again.

Connection verification fails: public key not registered or mismatched

• What happened: Simpplr generated a public key during setup, but it was not added to your Okta app, or a different key was added.

• What to do: In Simpplr, generate a new key and copy it. In Okta, open your API Services app, go to the General tab, and under Client Credentials, click Edit. Set Client authentication to Public key / private key, then add the new key under PUBLIC KEYS. Save and try verification again.

Connection verification fails: DPoP is still enabled

• What happened: The Okta app still has the Require Demonstrating Proof of Possession (DPoP) header in token requests option turned on. Simpplr does not support DPoP.

• What to do: Open your API Services app in Okta, go to the General tab, click Edit under General Settings, and clear the DPoP checkbox. Save and try verification again.

Sync cannot read users, apps, or groups

• What happened: The required API scopes were not granted to your API Services app in Okta.

• What to do: In Okta, open your API Services app and go to the Okta API Scopes tab. Make sure okta.users.read, okta.apps.read, and okta.groups.read all show as Granted. Grant any that are missing, then click Test in Simpplr to verify again.

The Okta API token stops working

• What happened: The API token used to authenticate the connection was deleted or revoked in Okta.

• What to do: Create a new API token in Okta under Security > API > Tokens and enter it in Simpplr. For new connections, switch to Okta Client OAuth instead, as API tokens are no longer available for new setups.

FAQs

Q: Can I switch from an API token to OAuth without losing my existing sync settings?

Ans: Yes. Your existing sync settings and field mappings are preserved when you migrate. After OAuth verification succeeds, the connection uses OAuth automatically.

Q: Should I revoke my old API token after migrating to OAuth?

Ans: Yes, as a security best practice. In Okta, revoke the old API token under Security > API > Tokens once the OAuth connection has been verified and is working.

Q: Why is the API Token option not available when I set up a new connection?

Ans: API token-based connections are only supported for integrations that already use them. New connections must use Okta Client OAuth, which provides scoped, automatically rotating access and is more secure than long-lived API tokens.