How to Setup Okta Directory Sync

Overview

Learn how to connect your Okta directory to Opensense so your organization's users and groups sync automatically. Once configured, Opensense pulls directory data daily to keep your email signature employee data up to date.

Before you start

Make sure you have:

• Super Admin access in Okta (required to create API tokens)

• Access to securely share credentials with the Opensense implementation team

Step-by-step guide

Step 1: Navigate to API token settings

1. Log in to the Okta Admin Console as a Super Admin

2. Go to Security → API

3. Click the Tokens tab

Expected result: You see the API Tokens page with a Create token button.

Step 2: Create an API token

1. Click Create token

2. Enter a name for the token (for example, "Opensense Directory Read")

3. For API calls made with this token must originate from, select Any IP

4. Click Create token

Expected result: A dialog displays "Token created successfully!" with your Token Value.

Step 3: Copy and save the token

1. Click the copy icon next to the Token Value to copy it

2. Save the token in a secure location

3. Click OK, got it

⚠️ Warning: This is the only time you can view the token. After clicking "OK, got it," Okta stores the token as a hash and you cannot retrieve it. If you lose the token, you must create a new one.

Expected result: You have the API Token saved securely.

Step 4: Get your Instance URL

Your Instance URL is your Okta domain. Find it in your browser address bar while logged into the Admin Console.

Examples:

• https://yourcompany.okta.com

• https://login.yourdomain.com

Expected result: You have both the Instance URL and API Token saved.

Step 5: Provide credentials to Opensense

Share the following information securely with your Opensense implementation team:

ℹ️ Info: Use a secure method to share credentials, such as a password manager or encrypted communication channel.

Step 6: Verify the connection

Once Opensense configures your credentials, verify the sync is working:

1. In Opensense, click Manage in the navigation bar

2. Click Users

3. Click Action in the upper right corner

4. Click Run Sync

5. Confirm Okta appears as a source and the sync completes successfully

Expected result: Users and groups from Okta appear in Opensense. The sync runs automatically once daily after initial setup.

Troubleshooting

Invalid token

Cause: The API Token was entered incorrectly, revoked, or has expired.

Solution:

1. In Okta, go to Security → API → Tokens

2. Check if your token appears in the list and is active

3. If the token is missing or inactive, create a new token and share it with Opensense

ℹ️ Info: API tokens are valid for 30 days and automatically renew each time Opensense syncs. Since syncs run daily, tokens remain active. A token only expires if unused for 30+ consecutive days.

Access denied

Cause: The token was created by an admin without sufficient permissions.

Solution:

1. Verify the token was created by a Super Admin

2. If not, have a Super Admin create a new token

3. Share the new token with Opensense

Sync delays

Cause: The automated sync runs once daily. New users or groups may not appear immediately.

Solution:

1. In Opensense, go to Manage → Users

2. Click Action → Run Sync to trigger a manual sync

3. If issues persist, contact Opensense Support

Still having issues?

Contact Opensense Support for help:

• Email: help@opensense.com

• Knowledge Base: help.opensense.com

ℹ️ Info: When contacting support, include:

• Screenshots of any error messages

• Your Instance URL (do not share your API Token in screenshots)

• Steps you've already tried