Configure Opti ID for CMS 12

  • Updated

Opti ID provides multiple options for managing user identity and permissions so you can choose the best fit for your organization.

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.

Prerequisite

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

Option 1: Configure local login

Local login configures Opti ID-specific accounts for invited users. You manage user identity and permissions within Opti ID.

  1. 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.
  2. (Optional) Brand your login page.
  3. Review the local user password policy and how to reset your password.
  4. (Optional) Configure multi-factor authentication (MFA).
  5. Install, enable, test, and run Opti ID for CMS 12.
    1. Install Opti ID NuGet Package for CMS 12
    2. Remove existing virtual role mappings
    3. (Conditional) Enable Opti ID for Search & Navigation
    4. (Optional) Set Opti ID as the default authentication scheme
    5. Enable Opti ID for CMS 12
    6. Test Opti ID for CMS 12
    7. Run Opti ID for CMS 12
    8. (Optional) Bypass the Opti ID login page and redirect to the upstream IdP for CMS 12
  6. Review the system roles for your Optimizely products. If you want to personalize permission levels, create custom roles.
  7. Create groups to simplify the process of giving multiple users the same level of access.
  8. 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.

  1. 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.
  2. (Optional) Brand your login page.
  3. Configure SSO. You can configure up to five SSO connections if needed. You can use any IdP that supports SAML or OIDC protocols.
    1. Configure the SAML or OIDC SSO connection in your IdP.
    2. (Optional) Sync groups from your IdP to Opti ID.
    3. (Optional) Configure organizational domains to automatically provision users who log in with a specific domain.
    4. (Optional) Enable IdP-initiated login for a more seamless login experience.
  4. 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.
    1. Install Opti ID NuGet Package for CMS 12
    2. Remove existing virtual role mappings
    3. (Conditional) Enable Opti ID for Search & Navigation
    4. (Optional) Set Opti ID as the default authentication scheme
    5. Enable Opti ID for CMS 12
    6. Test Opti ID for CMS 12
    7. Run Opti ID for CMS 12
    8. (Optional) Bypass the Opti ID login page and redirect to the upstream IdP for CMS 12
  5. Review the system roles for your Optimizely products. If you want to personalize permission levels, create custom roles.
  6. Create groups to simplify the process of giving multiple users the same level of access.
  7. 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

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.

  1. 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.
  2. (Optional) Brand your login page.
  3. Configure SSO. You can configure up to five SSO connections if needed. You can use any IdP that supports SAML or OIDC protocols.
    1. Configure the SAML or OIDC SSO connection in your IdP.
    2. (Optional) Enable IdP-initiated login for a more seamless login experience.
  4. Configure SCIM in your IdP. If you create multiple SSO connections, you can only use SCIM for one of those SSO connections.
  5. 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.
    1. Install Opti ID NuGet Package for CMS 12
    2. Remove existing virtual role mappings
    3. (Conditional) Enable Opti ID for Search & Navigation
    4. (Optional) Set Opti ID as the default authentication scheme
    5. Enable Opti ID for CMS 12
    6. Test Opti ID for CMS 12
    7. Run Opti ID for CMS 12
    8. (Optional) Bypass the Opti ID login page and redirect to the upstream IdP for CMS 12
  6. Review the system roles for your Optimizely products. If you want to personalize permission levels, create custom roles.
  7. Create groups in your SCIM app to simplify the process of giving multiple users the same level of access.
  8. 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.OptimizelyIdentity

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

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

  1. Log in to the Opti ID Admin Center.

  2. Go to Product Access > Products > Optimizely Content Management System.

  3. Select the CMS instance for which you want to enable Opti ID.
  4. Go to the Details tab and click Edit.

  5. Select Opti ID Enabled and click Save.

Checking Opti ID Enabled prepares your DXP environment, but does not impact existing authentication on the site. You cannot undo this, so ensure you are ready to move forward. It can take up to an hour before Opti ID finishes fully provisioning.

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.

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

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

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:

  1. Log in to the Opti ID Admin Center.
  2. Go to Settings > Authentication > SSO.

  3. Expand the SSO connection details by clicking your SSO name.

  4. Copy the IdP ID after the equal sign (=) in the IDP-Initiated URL value in the SSO Connection Details section. For example, 0abcde34XY1zGhIjk890.

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

hrm.png

FAQs

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);

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.