Opti ID and Graph Adoption

By Optimizely Education
Published: Mar 16, 2026
Rating 1 star 2 stars 3 stars 4 stars 5 stars

Average rating: 0 No reviews

Outline

At a glance

Architectural shift: CMS 13 transitions from local code optimizations to mandatory service-bound dependencies.
Identity gate: Opti ID is now the required authentication layer for all technical and editorial administration.
Data gate: Optimizely Graph replaces legacy search and serves as the backbone for Visual Builder.
Critical path: Failure to configure these services results in edit mode lockouts and broken content delivery.

Upgrading to Optimizely CMS 13 PaaS introduces a paradigm shift in how applications handle identity and data delivery. Unlike previous version bumps that were primarily code-level optimizations, CMS 13 is service-bound. Specifically, Opti ID and Optimizely Graph function as "gating requirements"—architectural prerequisites that must be active and configured for the application to be fully functional within the Optimizely One ecosystem.

1. The Identity Gate: Centralized Authentication with Opti ID

In CMS 12, internal user management was often decentralized, utilizing local ASP.NET Core Identity tables or individual OIDC configurations. CMS 13 mandates the adoption of Opti ID for all technical and editorial administration. This is not an optional feature but a core dependency for accessing the CMS shell and administrative interfaces.

Technical impact on Identity Configuration

Transitioning to Opti ID requires a refactoring of the authentication pipeline. Developers must shift from local identity providers to Optimizely’s centralized SSO. This involves integrating the EPiServer.Cms.UI.OptimizelyIdentity or similar packages specifically updated for version 13.x.

The configuration within Startup.cs or Program.cs must be adjusted to register the Optimizely identity services. A critical technical detail is the useAsDefault parameter, which determines if Opti ID handles the primary authentication scheme for the entire application environment.

// Example configuration for enabling Opti ID in the middleware pipeline
public void ConfigureServices(IServiceCollection services)
{
    // Mandatory Opti ID registration for CMS 13
    services.AddOptimizelyIdentity(useAsDefault: true);
    
    // Additional configuration for shell modules
    services.Configure<AuthenticationOptions>(options => 
    {
        options.DefaultAuthenticateScheme = OptimizelyIdentityDefaults.SchemeName;
        options.DefaultChallengeScheme = OptimizelyIdentityDefaults.SchemeName;
    });
}

The Role Mapping Requirement

A material change in identity management is the shift of the "source of truth." While CMS role-based access control (RBAC) still exists within the Admin UI, the definition of users and their high-level group memberships now resides in the Opti ID Admin Center. During the upgrade "gate" evaluation, technical teams must audit existing local roles and ensure they are ready to be mapped to centralized Opti ID groups.

2. The Data Gate: Optimizely Graph Activation

The second gating requirement is the move from legacy Search & Navigation (formerly Optimizely Find) to Optimizely Graph. In CMS 13, Graph provides the infrastructure for content indexing, querying, and delivery.

PaaS Portal Requirements

For CMS 13 PaaS implementations, activation occurs at the infrastructure level before code deployment can be fully validated. The activation gate involves a specific self-service flow within the Optimizely PaaS (DXP) portal:

Navigate to the DXP Project: Access the organizational project in the PaaS management interface.
API Tab Access: Within the technical management console, locate the API tab.
Instance Provisioning: Add a Graph instance via the self-service flow. This step is mandatory to generate the necessary keys and endpoint addresses required for the CMS 13 application to synchronize content.

The Dependency on Visual Builder

The logic for adopting Graph extends beyond search functionality. CMS 13 introduces Visual Builder, a modern visual authoring and staging environment. Visual Builder is fundamentally dependent on Optimizely Graph to retrieve and staging content context. If the Graph gate is bypassed or improperly configured, the application will lose access to these core authoring capabilities, rendering many of the CMS 13 platform benefits inaccessible.

3. Technical Configuration and Constraints

While Optimizely Graph is pre-configured within the DXP environment, local development and validation environments require explicit configuration settings. These must be maintained in the appsettings.json or as environment variables during the readiness phase.

{
  "Optimizely": {
    "ContentGraph": {
      "GatewayAddress": "https://cg.optimizely.com",
      "AppKey": "your-hmac-public-key",
      "Secret": "your-hmac-secret-key",
      "SingleKey": "your-public-site-key",
      "AllowSendingLog": true
    }
  }
}

Functional Gaps and Constraints

During the gating evaluation, technical teams should identify functional gaps. Pre-release versions of CMS 13 may have specific constraints regarding total index size or the availability of advanced Graph filtering (such as semantic search) depending on the provisioning tier. Operating within these constraints is a requirement for calling an upgrade "production-ready."

4. Breakpoints: Consequences of Non-Adoption

If Graph and Opti ID are treated as optional package upgrades rather than gating requirements, the following operational breakpoints should be expected:

Edit Mode Lockouts: Internal users will be unable to log into the CMS shell if the Opti ID SSO handshake is not properly established in the DXP environment.
Indexing Failures: CMS 13 will attempt to push content events to the Graph endpoint. Without a provisioned instance, the content cache and delivery pipeline may exhibit inconsistent behavior.
Visual Authoring Failures: Editors will experience broken previews and error states within the Visual Builder interface if content context cannot be resolved via GraphQL.

Conclusion

Adopting Optimizely Graph and Opti ID represents a strategic shift from local application management to platform-integrated infrastructure. Transitioning through these gates is essential for ensuring environment stability, user accessibility, and the enablement of modern authoring tools like Visual Builder. By prioritizing these service-bound requirements early in the upgrade lifecycle, technical teams establish a reliable foundation that mitigates operational risk and facilitates the full exploitation of the CMS 13 ecosystem.