Create a SCIM provisioning app in Okta

19 min

Note

Optimizely officially supports SCIM provisioning with Entra ID, Okta, and PingOne. Other IdPs are not officially supported for SCIM provisioning, and Optimizely does not assist with custom configuration or troubleshooting.

You can configure an Okta enterprise app integration that uses System for Cross-domain Identity Management (SCIM) for provisioning. This securely automates and manages user identity information, such as user and group creation, updates, and deactivation, from Okta to Opti ID.

This article describes how to create a separate Okta app for SCIM provisioning than you use for SSO (so you will have two separate Okta apps). With this setup, you can use Security Assertion Markup Language (SAML) or OpenID Connect (OIDC).

Important

If you use SAML and prefer to manage your SSO and SCIM provisioning in a single Okta app, see Create a single Okta app for SCIM provisioning and SAML SSO.

Prerequisites

Configure the SAML or OIDC SSO connection in your identity provider (IdP)SAML or OIDC SSO connection in your identity provider (IdP). If you intend to use your IdP for provisioning and SSO, the best practice is to use two separate apps in your IdP: one to manage the SCIM integration and one to manage the SSO integration.

Decide to use just-in-time (JIT) or SCIM for user and group provisioning. You cannot use JIT and SCIM at the same time. Default SSO in Opti ID uses JIT provisioning. Choosing SCIM automatically opts you out of JIT provisioning. Contact Optimizely Support to configure your SCIM organization.

You must be in the Admin Center Administrators group in the Opti ID Admin Center.

You must have administrator rights in your IdP account.

Note

If you create multiple SSO connections, you can only use SCIM for one of those SSO connections.

Add a SCIM app in Okta

Generate a SCIM token in Opti ID. This token is required for step 12. It is your responsibility to keep this token secure.

In your Okta Admin Console, go to Applications > Applications and click Browse App Catalog.

Note

If you already added the Opti ID app through the Configure SAML SSO with Okta article, skip to step 8.

Search for and select the SCIM 2.0 Test App (Header Auth) app, then click Add.

(Optional) Change the label for the app, then click Done.

On the Sign On tab, click Edit.

Ensure SAML 2.0 is selected.

In the Credentials Details section, select Email for Application username format.

Click Save.

Select Provisioning and then click Configure API Integration.

Select the Enable API Integration checkbox.

Enter https://identity-api.optimizely.com/api/scim/v2 for the base URL.

Paste the token you generated from Generate a SCIM token in Opti ID.

Click Test API Credentials to test whether the integration can connect to the SCIM API. If there are errors, make sure your base URL and API token are correct and try again.

Click Save to finish the integration setup.

Configure provisioning options

Next, configure SCIM options so the application knows how to handle the provisioning of the users and groups from Okta into Opti ID.

On the Provisioning tab of the Okta application, select To App and then click Edit.

Select the following checkboxes to enable these options:

Create Users – Enables Okta to create users in Opti ID, based on assigned users in Okta. If Okta detects an existing Opti ID user that has the same email address as an existing Okta user, Okta takes control of that Opti ID user. If there is not an existing Opti ID user with that email, Okta creates a user in Opti ID.

Update User Attributes – Enables Okta to update the name and email address of Opti ID users based on changes to those users in Okta.

Deactivate Users – Enables Okta to delete users in Opti ID when you unassign them from the application in Okta. Okta reinstates these users if you assign them back to the Opti ID SCIM application in Okta.

Click Save.

Customize user provisioning attribute mappings

After you configure provisioning to the application, you must configure Attribute Mappings. Keep only the fields that you can sync with Opti ID:

userName

givenName

familyName

You can unmap other listed attributes from the Profile Editor and then delete them from the mapping view because you cannot sync these values with Opti ID.

Sync initial set of users and groups to Opti ID

After you configure SCIM provisioning in Okta, follow these steps to sync your initial set of Okta users and groups with Opti ID.

Okta does not support using the same Okta group for assignments and for group push, so this may result in issues with no obvious error message. To maintain consistent group membership between Okta and Opti ID, use separate groups for assigning and pushing to Opti ID. See Okta's help articles about common group push issues and using the same group for application assignment and group push.

In Okta, go to Assignments, click Assign, and then select Assign to Groups to assign Okta users to groups that you want to sync to Opti ID.

If any of the users you select already exist in Opti ID, Okta takes control of them. If they do not already exist in Opti ID, Okta creates them.

Go to Push Groups, click Push Groups, and select Find groups by name to search for the Okta groups you want to add to Opti ID.

When you push the Okta group to Opti ID, Opti ID automatically creates an internal user group with the same name in the Opti ID Admin Center.

To sync additional groups, select Save & Add Another. When you are done adding Okta groups, click Save.

On the Provisioning tab in the Opti ID SCIM app, click Force Sync to initiate the sync process for the first time. The first sync may take some time to complete.

In the Opti ID Admin Center, go to Groups > Users and Groups > Groups to verify that users and groups synced correctly.

Limitations and usage tips

There are a few limitations and usage tips for how Okta integrates through SCIM 2.0.

User management in Okta

After the initial sync is complete, the users and groups in the Opti ID Admin Center should match the Okta users and groups that you chose.

Going forward, you must manage those users and groups in Okta as they are mostly read-only from Opti ID. Any time you assign an Okta user to the Opti ID SCIM application and there is a delay in syncing users, go to the Provisioning tab of the app in Okta and click Force Sync.

The following changes you make in Okta are reflected in Opti ID:

Assigning and unassigning users from the application. Unassigning an Okta user from the Opti ID SCIM application deletes the user from Opti ID.

Deleting and unlinking groups from the application. Selecting Delete the group in the target app and unlinking the Okta group from the Opti ID SCIM application removes users from the group and deletes the group in Opti ID.

Activating and deactivating group push.

Adding and removing users from groups in Okta. Adding an Okta user to a group in the Opti ID SCIM application assigns the user to the corresponding group in Opti ID.

Opti ID does not support the following SCIM features:

Importing users and groups.

Synchronizing passwords.

Deactivating users. Instead, Optimizely deletes users when you deactivate them in your identity provider.

User management in Opti ID

SCIM syncs only groups and users from your SSO. Instances, roles, and permissions are managed within the Opti ID Admin Center. When using SCIM provisioning, performing a group push creates internal groups in Opti ID.

In addition to managing users and groups through your IdP, you have the flexibility to continue managing non-IdP users and groups directly through the Opti ID Admin Center:

Manually add collaborators or partners and groups.

You should manage your SSO users with an upstream IdP.

Assign a product instance to a group.

Assign roles to product instances.

Only make the following changes in your upstream IdP and let it flow downstream to Opti ID. Do not make these changes in the Opti ID Admin Center:

Edit users' first and last names. This causes a discrepancy between the IdP and Opti ID.

Edit group names and user memberships of groups provisioned from SCIM to Opti ID. This causes out-of-sync user assignments for your SSO users. Instead, create separate groups for collaborators or partners in Opti ID because those are not managed by SCIM provisioning.

Delete users and groups. This makes that resource unavailable for updates from the IdP.

The following groups are reserved only for internal Opti ID use. Do not link them to your Opti ID SCIM application:

Everyone

Admin Center Administrators

Okta has the option to suspend users but does not communicate this information to Opti ID. Doing this does not unassign the user from the Opti ID SCIM application and, therefore, does not suspend the corresponding Okta-managed user in Opti ID. Ensure you unassign or deactivate the Okta user in the Opti ID SCIM application to delete the user from Opti ID.

Options to avoid

Importing users and groups and linking groups are not supported. When unlinking an Okta group from Opti ID, you should not select the Leave the group in the target app option. Selecting that option causes the following to happen:

The corresponding Okta-managed group in Opti ID persists in a read-only state. You cannot delete the corresponding Okta-managed group in Opti ID.

Okta-managed users attached to the group continue to have the group's access and you cannot detach them from the group in Opti ID.

Troubleshoot

Okta's System Log records system events that are related to your organization, providing an audit trail that you can use to understand platform activity and diagnose problems. You should start with Okta's System Log when troubleshooting issues related to your Opti ID SCIM app in Okta.

Confirm user addition in Opti ID with Okta's System Log

Go to your Opti ID SCIM app in Okta.

Click View Logs.

Search for the specific user by adding and target.AlternateId eq "email_address" to the existing search query. Replace email_address with the user's email address.

Expand the entry where the Event Info column displays Successfully pushed new user account to app. Ensure the event was successful.

Within that expanded entry, expand the Event and Target attributes.

Event – Ensure that EventType displays app.user_management.push_new_user_success.

Target – Ensure the first target's AlternateId is the user's primary email, and the third target's AlternateId is the name of your Opti ID SCIM application in Okta.

Confirm user deletion in Opti ID with Okta's System Log

Go to your Opti ID SCIM app in Okta.

Click View Logs.

Search for the specific user by adding and target.AlternateId eq "email_address" to the existing search query. Replace email_address with the user's email address.

Expand the entry where the Event Info column displays Push user deactivation to external application. Ensure the event was successful.

Within that expanded entry, expand the Event and Target attributes.

Event – Ensure that EventType displays application.provision.user.deactivate.

Target – Ensure the first target's AlternateId is the user's primary email, and the third target's AlternateId is the name of your Opti ID SCIM application in Okta.

Confirm group addition in Opti ID with Okta's System Log

Go to your Opti ID SCIM app in Okta.

Click View Logs.

Search for the specific user by adding and target.DisplayName eq "group_name" to the existing search query. Replace group_name with the group's name.

Expand the entry where the Event Info column displays Group Push group [group name] pushed to app. Ensure the event was successful.

Within that expanded entry, expand the Event and Target attributes.

Event – Ensure that EventType displays application.provision.group_push.pushed.

Target – Ensure the first target's DisplayName is the name of the group you added, and the second target's AlternateId is the name of your Opti ID SCIM application in Okta.

Confirm group member addition in Opti ID with Okta's System Log

Go to your Opti ID SCIM app in Okta.

Click View Logs.

Search for the specific user by adding and target.AlternateId eq "email_address" to the existing search query. Replace email_address with the user's email address.

Expand the entry where the Event Info column displays Add user to application membership. Ensure the event was successful.

Within that expanded entry, expand the Event and Target attributes.

Event – Ensure that EventType displays application.user_membership.add.

Target – Ensure the first target's AlternateId is the user's primary email, and the second target's AlternateId is the name of your Opti ID SCIM application in Okta.

Confirm group member removal in Opti ID with Okta's System Log

Go to your Opti ID SCIM app in Okta.

Click View Logs.

Search for the specific user by adding and target.AlternateId eq "email_address" to the existing search query. Replace email_address with the user's email address.

Expand the entry where the Event Info column displays Remove user's application membership. Ensure the event was successful.

Within that expanded entry, expand the Event and Target attributes.

Event – Ensure that EventType displays application.user_membership.remove.

Target – Ensure the first target's AlternateId is the user's primary email, and the second target's AlternateId is the name of your Opti ID SCIM application in Okta.

Frequently Asked Questions (FAQ)

If your organization is already onboarded to Opti ID using SSO and JIT, what happens to existing users when your organization switches to using SCIM?

There will not be any issues with users created in the Opti ID Admin Center, as these users are mapped to newly assigned groups from the upstream IdP during SCIM provisioning.

If your organization is already onboarded to Opti ID using SSO and JIT, what happens to existing groups when your organization switches to using SCIM?

Opti ID has three group types. See Manage groups for the list of group types and their descriptions.

If your organization wants to manage users with groups that have the same name as previously created Custom groups in Opti ID, then you must delete those groups in Opti ID before enabling SCIM provisioning.

You cannot delete Product user groups in Opti ID. When you enable SCIM, any group you create on your side cannot have the same name as a Product group in Opti ID. You must pick a different name (like, Opti_SCIM_<existing-Product-user-group-name>) and assign that SCIM group the same access that the corresponding group has in Opti ID. After you enable SCIM, do not use previously defined Product groups.