Setting up Okta directory sync

Overview

Connect your Okta directory to Opensense, so your organization’s users and groups sync automatically. Once it’s set up, Opensense pulls directory data daily, to keep your email signature employee data up to date.

Before you start

You need:

• Super Admin access in Okta (required to create API tokens)
• A way to share credentials securely with the Opensense implementation team

Step-by-step guide

Step 1: Go to the API token settings

1. Sign in to the Okta Admin Console as a Super Admin.
2. Go to Security > API.
3. Select the Tokens tab.

You see the API Tokens page, with a Create token button.

Step 2: Create an API token

1. Select 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. Select Create token.

A dialog shows “Token created successfully!”, with your Token Value.

Step 3: Copy and save the token

1. Select the copy icon next to the Token Value, to copy it.
2. Save the token in a secure location.
3. Select OK, got it.

You can only see the token once

This is the only time you can view the token. After you select OK, got it, Okta stores the token as a hash, and you can’t retrieve it. If you lose the token, you must create a new one.

You now have the API token saved securely.

Step 4: Get your Instance URL

Your Instance URL is your Okta domain. You can find it in your browser’s address bar while you’re signed in to the Admin Console. For example:

• https://yourcompany.okta.com
• https://login.yourdomain.com

You now have both the Instance URL and the API token saved.

Step 5: Give the credentials to Opensense

Share this information securely with your Opensense implementation team:

Instance URL

Your Okta domain URL, for example https://yourcompany.okta.com

API Token

The token value you copied

Share credentials securely

Use a secure method to share credentials, such as a password manager or an encrypted communication channel.

Step 6: Check the connection

Once Opensense configures your credentials, check that the sync works:

1. In Opensense, select Manage in the navigation bar.
2. Select Users.
3. Select Action in the upper-right corner.
4. Select Run Sync.
5. Confirm that Okta appears as a source, and that the sync completes successfully.

Users and groups from Okta appear in Opensense. After the initial setup, the sync runs automatically once a day.

Troubleshooting

Invalid token

Cause: the API token was entered incorrectly, or was revoked, or has expired.

1. In Okta, go to Security > API > Tokens.
2. Check whether your token is in the list, and active.
3. If the token is missing or inactive, create a new token, and share it with Opensense.

API tokens are valid for 30 days, and renew automatically each time Opensense syncs. Because syncs run daily, tokens stay active. A token only expires if it isn't used for 30 or more days in a row.

Access denied

Cause: the token was created by an admin without enough permissions.

1. Check that a Super Admin created the token.
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 a day, so new users or groups may not appear right away.

1. In Opensense, go to Manage > Users.
2. Select Action > Run Sync to start a sync manually.
3. If issues continue, contact Opensense Support.

Still having issues?

Contact Opensense Support at help@opensense.com. Include:

• Screenshots of any error messages
• Your Instance URL (don’t show your API token in screenshots)
• The steps you’ve already tried

What’s next

• Running a directory sync manually
• Field data priority