Create a SCIM provisioning app in Okta

  • Updated

You can set up 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, between Okta and Opti ID.

User and group provisioning with SCIM lets you manage your organization’s users and groups in one place, and have those users and groups populate into Opti ID. Provisioning prevents the need to create a duplicate set of users and groups in Opti ID that already exist in your identity management service.

With Opti ID and SCIM, users and groups are first set up in your identity provider and then provisioned down to Opti ID. After you set up SCIM provisioning, changes that you make to users and groups at the source identity provider sync down to Opti ID using the SCIM protocol. You should not edit users and groups that SCIM provisioned into Opti ID, directly in Opti ID. Instead, make changes to the users and groups at the source identity provider, so you can sync these changes downstream into Opti ID with SCIM.

Prerequisites

  • Configure single sign-on (SSO).

    If you intend to use Okta for provisioning and SSO, the best practice is to use two separate Okta apps: 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 Okta account.

Supported provisioning features

The following SCIM provisioning features are supported by Opti ID:

  • Push users – Users that you assign to the Opti ID SCIM application in Okta are automatically added as users in Opti ID.
  • Update user attributes – When you update user attributes in Okta (like first name and last name), they are updated in Opti ID.
  • Deactivate users – When you deactivate users in Okta or unassign them from the Opti ID application, they are deleted in Opti ID.
  • Push groups – Groups and their users in Okta are pushed to Opti ID.

Add a SCIM app in Okta

  1. Request your SCIM token from Optimizely Support. This token is required for step 10. It is your responsibility to keep this key secure.
  2. In your Okta Admin Console, go to Applications > Applications and click Browse App Catalog.
    If you already added the Opti ID app through the Configure SSO with Opti ID using SAML article, skip to step 8.
  3. Search for and select the SCIM 2.0 Test App (Header Auth) app, then click Add.
  4. (Optional) Change the label for the app, then click Done.
  5. On the Sign On tab, click Edit.
  6. In the Credentials Details section, select Email for Application username format.
  7. Click Save.
  8. Select Provisioning and then click Configure API Integration.
  9. Select the Enable API Integration checkbox.
  10. Paste the token you received from Optimizely Support in the Secret Token field.
  11. 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.
  12. 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.

  1. On the Provisioning tab of the Okta application, select To App and then click Edit.
  2. 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.
  3. 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, you must configure a separate group to push groups to the target app. See Okta's help articles about common group push issues and using the same group for application assignment and group push.
  1. 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.
  2. 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.

    • If an Opti ID group with the same name does not already exist, you can create the group or link this group to an existing Opti ID group of a different name.
    • To sync additional groups, select Save & Add Another. When you are done adding Okta groups, click Save.
  3. 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.

  4. 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

In addition to managing users and groups through Okta, you have the flexibility to continue managing non-Okta 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 identity provider.
  • Assign a product instance to a group.
  • Assign roles to product instances.

Only make the following changes in your upstream identity provider 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 identity provider 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 identity provider.

Okta has an 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.

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

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

  1. Go to your Opti ID SCIM app in Okta.
  2. Click View Logs.
  3. 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.
  4. Expand the entry where the Event Info column displays Successfully pushed new user account to app. Ensure the event was successful.
  5. 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

  1. Go to your Opti ID SCIM app in Okta.
  2. Click View Logs.
  3. 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.
  4. Expand the entry where the Event Info column displays Push user deactivation to external application. Ensure the event was successful.
  5. 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

  1. Go to your Opti ID SCIM app in Okta.
  2. Click View Logs.
  3. 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.
  4. Expand the entry where the Event Info column displays Group Push group [group name] pushed to app. Ensure the event was successful.
  5. 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

  1. Go to your Opti ID SCIM app in Okta.
  2. Click View Logs.
  3. 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.
  4. Expand the entry where the Event Info column displays Add user to application membership. Ensure the event was successful.
  5. 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

  1. Go to your Opti ID SCIM app in Okta.
  2. Click View Logs.
  3. 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.
  4. Expand the entry where the Event Info column displays Remove user's application membership. Ensure the event was successful.
  5. 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 will happen to existing users when your organization is switched 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 provider during SCIM provisioning.

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

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