Getting Started

Before you set up Okta as your IDP, you must first create an Okta Directory App in Opal. To do this, please follow the instructions here.

Next, go to the Configuration section and navigate to Settings, then Identity and HR Providers. Click Connect next to Identity Provider.

On the next page, click Connect under the Okta logo.

Your Okta IDP setup is now complete!

Importing IDP user attributes

Importing custom user attributes

Once your Okta IDP is connected, you can configure Opal to import your custom user attributes by specifying an allowlist that you want imported. To do this, click Importing 0 custom attributes under your Okta Identity Provider integration.

This will open a modal that lets you specify all the attribute names you want to import. Please be sure to specify the variable name, and not the display name, from the Okta profile editor.

Attributes can be configured to be interpreted as specific values, such as a user's title or integration-specific username. You can also choose "Custom" for attributes that should only be imported as readable tag values for the user:

Importing user manager

You can configure Opal to automatically import user manager information from Okta and match the imported string to an Opal user.

There are 2 ways to do this:

• Set the manager attribute in an Okta user's profile to an Okta user's email. If there is a matching Opal user associated with this Okta user email, the user's manager in Opal will be updated to this user.
• Set the managerId attribute in an Okta user's profile to an Okta user ID. If there is a matching Opal user associated with this Okta user ID, the user's manager in Opal will be updated to this user. The Okta user ID can be found by navigating to the user from the People section in a browser, then observing the Okta user ID at the end of the URL (below, the Okta user ID is 00u1835qib5TKa8Ri5d7).

Importing user secondary email(s)

If users in your organization can have multiple email addresses, it's often helpful to consolidate their access footprint under a single Opal account.

You can do this by configuring Opal to import user secondary emails from your IDP. When you do this, Opal will link users to all third-party user accounts registered under their secondary email. For example:

• Suppose a user Alice has primary email [email protected] and secondary email [email protected].
• Suppose that Alice's Salesforce account is listed under her secondary email, [email protected].
• When syncing with Salesforce, Opal will recognize that [email protected] belongs to Alice, and will represent this Salesforce account's access under Alice's Opal account.
• When Alice is granted access to Salesforce via Opal, Opal will propagate access to Salesforce under [email protected] rather than under Alice's primary email.

To set this up, add a custom attribute mapping to Secondary email (for details on how to do this, see the section Importing custom user attributes). If your users can have more than 1 secondary email, you can configure Opal to import multiple Secondary email attributes.

Auto-merging users by secondary email

Even after you've set up user secondary email import, it's possible for a single user identity to have 2 Opal user accounts — one for their primary email, and one for their secondary email. This can happen if the secondary Opal account was created before a primary Opal account's secondary email was updated.

When this happens, it's helpful to merge these 2 Opal user accounts. To do this, go to your organization's IDP settings and change the setting for Auto-merge Opal users based on secondary email to Enabled:

When this setting is enabled, Opal users whose email matches the secondary email of another Opal user will be auto-merged during IDP sync.

📘

How auto-merging works

In an auto-merge of two Opal users, one Opal user is preserved and the other is deleted. All user data associated with the deleted Opal user is removed. The preserved user is updated as follows:

• Primary and secondary emails are immediately updated to the correct values.
• IDP user attributes will be imported in the following sync.
• End-system access for both users will be imported and associated with the preserved user in the following sync. (Notably, no access changes are propagated to any end-systems in an auto-merge.)

Opal decides which user to preserve by examining which user has logged in more recently. Only logins after Feb 14, 2023 (Opal Cloud) or after v1.0.396 (Opal Self-Host) are considered.

❗️

Auto-merging relies on the secondary email(s) imported from your IDP to be accurate. Inaccurate secondary emails will result in unintended and potentially irreversible auto-merges.