Create a SCIM provisioning app in Microsoft Entra ID

  • Updated

You can set up a Microsoft Entra ID 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 Entra ID 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 in 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 Entra ID for provisioning and SSO, the best practice is to use two separate Entra ID apps: one to manage the SCIM integration and one to manage the SSO integration. In this case, you only have to create groups in the SCIM app.

  • 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 the Application Administrator, Cloud Application Administrator, or Global Administrator role in Entra ID.

Add a SCIM app in Entra ID

  1. In the Entra ID portal, go to Manage > Enterprise Applications and click + New application to create an enterprise application.
  2. Click + Create your own application.
  3. Enter a descriptive name for your app, and then select Integrate any other application you don’t find in the gallery (non-gallery) to create your own app instead of using a published gallery app.

Configure provisioning options

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

  1. Request your SCIM token from Optimizely Support. This token is required for step 3. It is your responsibility to keep this key secure.
  2. In the Provisioning section of the Entra ID app, click Get Started.

  3. Complete the following provisioning properties to use the HTTP header authentication method:
    • Provisioning Mode – Set to Automatic.

    • Tenant URL – Enter https://identity-api.optimizely.com/api/scim/v2.

    • Secret Token – Paste the SCIM token you received from Optimizely Support.

  4. Click Test Connection to test whether the app can connect to your SCIM API. If there are errors, make sure your tenant URL and secret token are correct and try again.
  5. Click Save.

Customize user provisioning attribute mappings

  1. In the Provisioning section of the Entra ID app, expand Mappings to view and edit the user attributes that flow between Entra ID and Opti ID.
  2. For each user mapping, delete all attributes except the following:
    • userName (You should have this mapped with an email address)
    • active
    • name.givenName
    • name.familyName
  3. Similarly, for the group mappings, delete all attributes except the following:
    • displayName
    • members
  4. Set Provisioning Status to On.

After you complete the provisioning, there may be a delay in the user information syncing from Entra ID to Opti ID because of Entra ID's sync schedule. Entra ID syncs every 40 minutes.

To force a sync for an individual user, go to Provisioning > Provision on Demand, then search for and select the user.

Limitations and usage tips

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

User management in Entra ID

If you delete or deactivate a user in Entra ID:

  • The user is unassigned from all groups in Opti ID.
  • The user is deleted in Opti ID.

If you restore that same user in Entra ID:

  • The user is created in Opti ID.
  • The user is assigned to the Opti ID groups that are assigned to them in Entra ID.

User management in Opti ID

In addition to managing users and groups through Entra ID, you have the flexibility to continue managing non-Entra ID 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.

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

Troubleshoot

You can troubleshoot using Microsoft Entra ID provisioning logs to find:

  • Which groups were successfully created and removed
  • Which users were successfully created and removed
  • Which users were assigned to or removed from the Opti ID SCIM provisioning app
  •  

If there are any issues with provisioning:

  1. Unassign all the users and user groups from the Opti ID SCIM app.
  2. Wait about 40 minutes for the sync to complete.
  3. Reassign users and user groups to the Opti ID SCIM app.

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.