Configure Opti ID for CMS 12
Opti ID provides multiple options for managing user identity and permissions so you can choose the best fit for your organization.
- Local login – Invited users configure Opti ID-specific accounts. You manage user identity and permissions within Opti ID.
- SSO without SCIM – Invited users log in to Opti ID through an Opti ID single sign-on (SSO) app that you add to your identity provider's (IdP's) app portal. See Overview of configuring your own SSO for Opti ID. You manage user permissions within Opti ID.
- SSO with SCIM – Invited users log in to Opti ID through IdP. You manage user identity and permissions within your IdP and automate the information flow between your IdP and Opti ID. See Overview of SCIM provisioning for Opti ID.
Note
Opti ID lets you configure up to five SSO connections for your organization. If you create multiple SSO connections, you can only use SCIM for one of those SSO connections.
Go to the corresponding section for the configuration you want to implement.
Prerequisites
Provision your Optimizely Content Management System (CMS) 12 instances on DXP. Opti ID is only available for CMS 12 instances hosted on DXP.
Configuration options
Note
Opti ID is only for users of Optimizely products.
Option 1: Configure local login
Local login configures Opti ID-specific accounts for invited users. You manage user identity and permissions within Opti ID.
- Complete the initial technical contact login. This person logs into Opti ID first and configures it for the rest of your organization. Contact your Customer Success Manager (CSM) if you do not know who the technical contact is. You can change the technical contact later.
- (Optional) Brand your login page.
- Review the local user password policy and how to reset your password.
- (Optional) Configure multi-factor authentication (MFA).
- Install, enable, test, and run Opti ID for CMS 12.
- Review the system roles for your Optimizely products. If you want to personalize permission levels, create custom roles.
- Create groups to simplify the process of giving multiple users the same level of access.
- Invite users, assigning them to roles or groups so that they have the appropriate access to your CMS instance.
Option 2: Configure SSO without SCIM
SSO without SCIM lets invited users log in to Opti ID through an Opti ID SSO app that you add to your IdP's app portal. You manage user permissions within Opti ID.
- Complete the initial technical contact login. This person logs into Opti ID first and configures it for the rest of your organization. Contact your CSM if you do not know who the technical contact is. You can change the technical contact later.
- (Optional) Brand your login page.
- Configure SSO. You can configure up to five SSO connections if needed. You can use any IdP that supports SAML or OIDC protocols.
- (Optional) Sync groups from your IdP to Opti ID.
- (Optional) Configure organizational domains to automatically provision users who log in with a specific domain.
- (Optional) Enable IdP-initiated login for a more seamless login experience.
- Install, enable, test, and run Opti ID for CMS 12. You can also optionally configure Opti ID to bypass the Opti ID login page and go directly to your upstream IdP login page.
- Review the system roles for your Optimizely products. If you want to personalize permission levels, create custom roles.
- Create groups to simplify the process of giving multiple users the same level of access.
- Invite users, assigning them to roles or groups so that they have the necessary access to your CMS instance.
Option 3: Configure SSO with SCIM
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.
SSO with SCIM lets you manage user identity and permissions within your IdP and automate the information between your IdP and Opti ID.
- Complete the initial technical contact login. This person logs into Opti ID first and configures it for the rest of your organization. Contact your CSM if you do not know who the technical contact is. You can change the technical contact later.
- (Optional) Brand your login page.
- Configure SSO. You can configure up to five SSO connections if needed. You can use any IdP that supports SAML or OIDC protocols.
- (Optional) Enable IdP-initiated login for a more seamless login experience.
- Configure SCIM in your IdP. If you create multiple SSO connections, you can only use SCIM for one of those SSO connections.
- Create a SCIM provisioning app in Microsoft Entra ID – Use OIDC or SAML for SSO, and manage SSO and SCIM on two separate Entra ID apps.
- Create a SCIM provisioning app in Okta – Use OIDC or SAML for SSO, and manage SSO and SCIM on two separate Okta apps.
- Create a single Okta app for SCIM provisioning and SAML SSO – Use only SAML for SSO, and manage SSO and SCIM on a single Okta app.
- Create a SCIM provisioning app in PingOne – Use OIDC or SAML for SSO, and manage SSO and SCIM on two separate PingOne apps.
- Install, enable, test, and run Opti ID for CMS 12. You can also optionally configure Opti ID to bypass the Opti ID login page and go directly to your upstream IdP login page.
- Review the system roles for your Optimizely products. If you want to personalize permission levels, create custom roles.
- Create groups in your SCIM app to simplify the process of giving multiple users the same level of access.
- Add users to your SCIM app, assigning them to roles or groups so that they have the necessary access to your CMS instance.
Install, enable, test, and run Opti ID for CMS 12
Complete this section at the designated step in your chosen Opti ID configuration (for example, step 4 of option 2 in the Configuration Options section).
1. Install Opti ID NuGet package for CMS 12
Install the following NuGet package in your solution using the NuGet Package Manager in Visual Studio or the command line:
dotnet add package EPiServer.OptimizelyIdentityIn startup.cs in the ConfigureServices method, enable Opti ID with the following:
services.AddOptimizelyIdentity();2. Remove existing virtual role mappings
Opti ID automatically maps the virtual roles CmsEditors and CmsAdmins. You must remove any existing mappings for these roles.
If you are not using ASP.NET identity, you must also remove any calls to services.AddCmsAspNetIdentity<TUser>().
3. (Conditional) Enable Opti ID for Search & Navigation
If you are using Search & Navigation with CMS 12 and Opti ID, you must enable Search & Navigation within Opti ID.
Warning
services.AddFind() must be called after services.AddOptimizelyIdentity(). Calling it before will prevent the Search & Navigation menu from displaying correctly.
Prerequisite packages:
- EPiServer.OptimizelyIdentity 1.0.0 or higher
- EPiServer.CMS.UI 12.22.0 or higher
In startup.cs in the ConfigureServices method, add the following after your Opti ID configuration:
services.AddFind();Your startup.cs should look similar to the following:
services.AddOptimizelyIdentity(useAsDefault: false);
services.Configure<GlobalHeaderOptions>(o =>
{
o.UseCommonComponent = true;
o.ScriptBaseUrl = "https://[YOUR_WEBSITE].com";
});
services.AddFind();4. (Optional) Set Opti ID as the default authentication scheme
Optimizely enables Opti ID by default in protected shell modules, preview, and edit mode only. If you want to enable Opti ID as the default authentication scheme for the whole application, enable Opti ID using the following instead:
services.AddOptimizelyIdentity(useAsDefault: true);Using Opti ID as the default authentication scheme only works if you do not register other authentication schemes.
If you need more control over which authentication schemes to use at specific times, configure AuthenticationOptions and use a policy scheme. The namespace EPiServer.OptimizelyIdentity.OptimizelyIdentityDefaults contains constants if you need to reference the Opti ID scheme name while configuring.
5. Enable Opti ID for CMS 12
- Log in to the Opti ID Admin Center.
- Go to Product Access > Products > Optimizely Content Management System.
- Select the CMS instance for which you want to enable Opti ID.
- Go to the Details tab and click Edit.
- Select Opti ID Enabled and click Save.
Note
Checking Opti ID Enabled prepares your DXP environment but does not change authentication on your site. Authentication switches to Opti ID only when you deploy code that uses it.
To test before deploying to production, check this setting on a non-production instance, such as your integration environment. You cannot uncheck Opti ID Enabled after selecting it. Only enable it on instances where you intend to use Opti ID.
Provisioning takes up to an hour to complete after you check this setting.
6. Test Opti ID for CMS 12
Before testing, ensure you have assigned your user to at least one of the built-in system roles for CMS. Deploy the code changes to DXP to start testing or run the application by configuring Opti ID locally.
Note
You can access the edit and admin user interface (UI) on /ui/cms/ after you have installed Opti ID.
7. Run Opti ID locally
You can use Opti ID locally on any of the following URLs:
- https://localhost:5000
- https://localhost:5096
- https://localhost:6921
- https://localhost:7595
For this to work, you also need the following settings, which you can find in DXP Management Portal (PaaS Portal) > API > Opti ID dev key. You can only use keys from the integration environment locally. The system automatically provides these settings when the application is deployed to Optimizely Digital Experience Platform (DXP). Ensure you have enabled Opti ID under Products > CMS > Integrations > Details. See 5. Enable Opti ID for CMS 12
In appsettings.json, add the following to run Opti ID locally:
{
"EPiServer": {
"Cms": {
"OptimizelyIdentity": {
"InstanceId": "xxx",
"ClientId": "xxx",
"ClientSecret": "xxx"
}
}
}
}When you confirm Opti ID works locally, deploy the code changes to DXP, then continue to the next step for your chosen configuration option.
8. (Optional) Bypass the Opti ID login page and redirect to the upstream IdP for CMS 12
Note
This option is only available if you configure Opti ID with SSO (option two or three) using only one identity provider.
Complete the following to bypass the Opti ID login page so that users go directly to the upstream IdP login page:
- Log in to the Opti ID Admin Center.
- Go to Settings > Authentication > SSO.
- Expand the SSO connection details by clicking your SSO name.
- Copy the IdP ID after the equal sign (=) in the IDP-Initiated URL value in the SSO Connection Details section. For example, 0abcde34XY1zGhIjk890.
- Enable Opti ID by completing one of the following options:
- Option 1 – Run the following in startup.cs in the ConfigureServices method:
services.AddOptimizelyIdentity(
useAsDefault: false, // or true
options => options.IdentityProviderId = "ENTER YOUR IDP ID"
);- Option 2 – Run the following in appsettings.json:
{
"EPiServer": {
"Cms": {
"OptimizelyIdentity": {
"IdentityProviderId": "ENTER YOUR IDP ID"
}
}
}
}After you configure this, users do not need to enter their email address on the Opti ID login page (shown in the following image) and the system redirects them to the upstream IdP login page.
Opti ID access rights and upgrade to CMS 13
If you want to upgrade to CMS 13, ensure you migrate your access rights to Opti ID before you start the upgrade.
FAQs
For developers and product managers
Can my site visitors use ASP.NET Identity or any other authentication scheme?
Yes. The system enforces the Opti ID authentication scheme in protected shell modules, such as the edit and admin UI and add-ons. Enable any other authentication scheme and ensure the system does not have Opti ID set as the default authentication scheme:
services.AddOptimizelyIdentity(useAsDefault: false);Note: Opti ID is only for users who access Optimizely products. Site visitors who need gated content require a different authentication scheme.
For a single .NET app, follow the standard approach to add an OpenID Connect authentication scheme to a .NET application. To sync users and their roles during sign-in, see Sync users and roles from an external authentication provider. Syncing caches users and their roles in CMS so administrators can assign permissions to them.
Sync users and roles only when you assign content permissions to these users. Refer to the user and role sync section of that guidance. Do not set Opti ID as the default authentication scheme. See Set Opti ID as the default authentication scheme.
When you secure CMS content through roles instead of per-user permissions, skip the user sync step during sign-in. See Sync users and roles from an external authentication provider.
Why do I get an error in Okta when testing locally?
Ensure you are using one of the allowed URLs and running your application with HTTPS enabled.
Why does the edit UI not load and gives a 404 error?
Ensure you are accessing the CMS on the/ui/cms path.
Why do I need to enable Opti ID before I can test it?
To test your implementation in an integration environment, you must check Opti ID Enabled in the Admin Center for that instance. Checking the setting alone does not change authentication on your site. Authentication changes only when you deploy code that uses Opti ID. Enable the setting on a non-production instance and complete your testing before deploying to production.
What happens if I check Opti ID Enabled but do not deploy code that uses Opti ID?
Authentication on your site continues to work the way it did before. The setting prepares the environment but does not activate Opti ID. Leave the setting checked for as long as you need while you finish your implementation.
Can I uncheck Opti ID Enabled after I select it?
No. After you check Opti ID Enabled for an instance, the setting is permanent. Only enable it on instances where you intend to use Opti ID.
Why is the Search & Navigation menu missing after I enable Opti ID?
Earlier versions of Search & Navigation do not recognize the CmsAdminsrole that Opti ID assigns, so your account does not have the access that Search & Navigation requires. You might also see an HTTP 403 (access denied) error when you go to the Search & Navigation page directly, or the indexing job runs successfully but searching for pages or blocks in edit or view mode returns only media items.
Upgrade Search & Navigation to version 16.7.1 or later, which supports sites that use Opti ID. Version 16.7.1 was released on March 3, 2026.
For developers only
If my third-party add-on has admin pages (such as the Geta packages), are there additional considerations during Opti ID setup?
Yes. Set the authentication scheme explicitly to the scheme that the Opti ID package exposes. This lets the add-on authenticate back-end users.
What if I use something other than an email address as the user ID?
Opti ID assumes the user ID is the email address. Depending on the IdP configuration, the user ID can be a username, domain name, or other identifier that the IdP returns. Before you migrate, check the rights assigned to each user, such as approval steps, content, content type, language, and tabs. Convert those rights to roles first.
Are role names case-sensitive when matching to Opti ID roles?
Yes. CMS matches role names case-sensitively. When you move from original roles to Opti ID roles, the names must match exactly. For example, CMS treats cmsadmins and CMSAdmins as different roles.
For guidance on assigning access rights with Opti ID, see Set access rights with Opti ID in the developer documentation.