Access Rights

By Optimizely Education
Published: Feb 17, 2026
Rating 1 star 2 stars 3 stars 4 stars 5 stars

Average rating: 0 No reviews

Outline

At a glance:

Granular Control: Use IContentSecurityRepository to programmatically manage ACLs and break inheritance when necessary
Scalable Security: Virtual Roles decouple identity providers from the CMS, improving performance and environment-specific governance
Global Reach: ILanguageBranchRepository and LanguageLoaderOptions provide the framework for managing and retrieving multi-lingual content
Performance First: Minimize ACL depth and prefer group-based permissions to avoid database overhead and cache thrashing

In Optimizely CMS 12, the administration of access rights and language branches is established through a collection of specialized Repository APIs and security frameworks. These tools provide the technical infrastructure necessary to enforce editorial governance across complex multi-site and multi-lingual PaaS environments. For technical architects, mastering these programmatic interfaces is essential for automating site setup, securing sensitive data, and ensuring a performant user experience for both editors and end-users.

1. Programmatic Access Control: IContentSecurityRepository

Programmatic management of permissions is handled via IContentSecurityRepository. Access rights in Optimizely are based on Access Control Lists (ACLs) attached to content nodes.

The Access Control List (ACL) Model

Inheritance: By default, content items inherit their ACL from their parent node - no explicit permissions need to be set on every page.
Breaking Inheritance: Technical teams can programmatically "break" inheritance to provide explicit permissions for a specific branch of the page tree, isolating that branch from its parent's rules.
Access Levels: Permissions are defined using the AccessLevel enum, which includes Read, Create, Edit, Delete, Publish, and Administer. These can be combined with bitwise OR.

Implementation: Setting Node Permissions

To modify permissions programmatically, retrieve the security descriptor, create a writable clone, add the entry, then save the changes back to the repository.

public void GrantEditorPermission(ContentReference contentLink, string groupName)
{
    var securityRepository = ServiceLocator.Current.GetInstance<IContentSecurityRepository>();

    // 1. Get the current security descriptor
    var securityDescriptor = securityRepository.Get(contentLink);

    // 2. Create a writable clone
    var writableDescriptor = securityDescriptor.CreateWritableClone() as IContentSecurityDescriptor;

    // 3. Add or update access entry
    var entry = new AccessControlEntry(groupName, AccessLevel.Edit | AccessLevel.Read | AccessLevel.Publish);
    writableDescriptor.AddEntry(entry);

    // 4. Save the modified security descriptor
    securityRepository.Save(contentLink, writableDescriptor, SecuritySaveType.Replace);
}

2. Scalable Security with Virtual Roles

In enterprise PaaS environments, managing thousands of explicit user permissions is not scalable. Virtual Roles provide a high-performance alternative by mapping claims or conditions to roles dynamically at runtime.

Strategic Benefits

Identity Provider Decoupling: Virtual roles allow the CMS to recognize roles like "WebAdmins" even if the underlying identity provider (such as Azure AD) uses different claim names.
Performance: They eliminate the need to store static group memberships in the CMS database, reducing SQL overhead during login and permission checks.
Configuration-Driven: Most virtual roles are configured via appsettings.json, enabling environment-specific security governance without code changes.

JSON

"EPiServer": {
  "Cms": {
    "MappedRoles": {
      "Items": {
        "CmsAdmins": {
          "MappedRoles": [ "WebAdmins", "Administrator" ],
          "ShouldMatchAll": false
        }
      }
    }
  }
}

3. Managing Language Branches: ILanguageBranchRepository

The ILanguageBranchRepository is the technical authority for defining which languages are available within a CMS instance.

Core Capabilities

Enumeration: Retrieve all enabled or available language branches for use in site initialization or content migration scripts.
Lifecycle Management: Programmatically enable or disable languages for specific sites without UI intervention.
Default Language: Define the "Master" language branch, which acts as the reference for all translations. Content without a translation falls back to this branch.

public void ListAvailableLanguages()
{
    var languageRepository = ServiceLocator.Current.GetInstance<ILanguageBranchRepository>();

    // Get all enabled languages in the system
    var enabledLanguages = languageRepository.ListEnabled();

    foreach (var lang in enabledLanguages)
    {
        var culture = lang.Culture;
        var isEnabled = lang.Enabled;
    }
}

4. Globalization Mechanics and Language Loaders

Retrieving content in a multi-lingual environment requires precise control over language selection and fallback behavior.

LanguageLoaderOptions

When using IContentLoader, use LanguageLoaderOption to govern how the system handles missing translations:

FallbackWithMaster(): If the requested language version does not exist, the system returns the master language version rather than null or an exception.
MasterLanguage(): Always retrieves the master version regardless of the current request context - useful in background jobs or admin operations.

// Fetching a specific language version with master fallback
var content = _contentLoader.Get<PageData>(
    pageLink,
    new LoaderOptions { LanguageLoaderOption.FallbackWithMaster() }
);

Note: If no LanguageLoaderOption is specified, IContentLoader uses the current thread's culture. In background jobs or scheduled tasks, this may not match any available language and can return null - always specify an option explicitly in non-request contexts.

5. Performance and Governance Best Practices

Limit ACL Depth: Avoid breaking permission inheritance frequently. Deep trees with frequent breaks significantly degrade GetChildren performance, as the security subsystem must perform additional database joins for each check.
Prefer Groups over Users: Never assign permissions to individual usernames programmatically. Always use groups or virtual roles to keep the security model manageable and performant at scale.
Caching Security Checks: Optimizely caches ACLs in the object cache. Monitor high-frequency permission updates to avoid "cache thrashing" during intensive background processes that modify ACLs in a loop.
Restricting Translations: Use SiteDefinition to restrict language versions available to specific site branches, ensuring editors only maintain authorized locales and reducing accidental content in wrong languages.

Conclusion

Administering access rights and language branches in Optimizely CMS 12 requires a synthesis of repository API expertise and architectural foresight. By leveraging IContentSecurityRepository for granular control and Virtual Roles for scalable identity management, technical teams can build secured environments that thrive under enterprise load. Utilizing ILanguageBranchRepository and advanced language loader options ensures multi-lingual content delivery is both accurate and performant across the global PaaS infrastructure.

End-user eLearning

Upcoming events

Certification

Partner training

Community

All Topics