Virtual roles

Optimizely Content Management System (CMS) uses an extension of the Role concept called Virtual Roles. These are roles where the membership criteria is determined at runtime. In other words, the virtual role membership is not stored in the database, but depends on programmatic criteria that can vary with each request.

You can add virtual roles to claims by SupportsClaims. By default, the SupportsClaims property sets whether a claim is added to the current principal for the virtual role in which a user is member.

You can access the current principal object in several different ways. The recommended approach is to use EPiServer.Security.PrincipalInfo.CurrentPrincipal property. Alternate ways, such as System.Web.HttpContext.Current.User, are supported also.

If SupportsClaims="false" on the virtual role then virtual roles are only evaluated when you check access rights based on ACLs in CMS. Any principal.IsInRole calls for a virtual role returns false.

The following virtual roles are delivered with CMS:

• Anonymous
• Authenticated
• Creator
• Everyone
• Administrator
• CmsAdmins
• CmsEditors
• PackagingAdmins
• SearchAdmins
• SearchEditors

In addition to the predefined roles, you can create new virtual roles to allow access based on business rules, such as allowing access only during business hours. A common scenario is to define virtual roles that evaluate to true if the user is a member of role1 and role2, which can reduce the number of groups needed for setting the required permissions in CMS.

• Administrator – Needed to support localized versions of Windows, where the Administrators group was translated. The Administrators virtual role runs a localization-independent test for the Administrators group, thus eliminating the need to manually modify web.config or access rights in CMS.
• Creator – Only used when evaluating AccessControlLists in CMS and returns true if the current principal is the same as the Creator for an ACL.
• PackagingAdmins – Used for controlling access to the Add-ons (apps) menu option from where add-ons are managed.
• SearchAdmins – Used for controlling access to the Optimizely Search & Navigation user interface and the Clear Indexes screen. Optimizely Search & Navigation users who are not Administrators must be both WebEditors _and_SearchAdmins: WebEditors to access the edit view, and SearchAdmins to access Optimizely Find features.
• SearchEditors – Used to control access to the Optimizely Search & Navigation user interface. SearchEditors cannot execute the Clear Indexes action

The PackagingAdmins, CmsAdmins, CmsEditors, SearchEditors and SearchAdmins virtual roles are of the MappedRole type (used to map existent or non-existent groups to several other groups). The roles attribute contains the names of one or more roles that are used to evaluate membership in the MappedRole. There is property ShouldMatchAll that have the following values:

• false means that membership in at least one of the roles listed in the roles attribute is required for membership in the mapped role.
• true means that membership in all of the roles listed in the roles attribute is required for membership in the mapped role.

Example of Mapped Roles in appsettings.json:

...
"EpiServer" : {
  "Cms" : {
    "MappedRoles" : {
      "Items" : {
        "SearchAdmins" : {
          "MappedRoles" : [ "WebAdmins", "Administrators" ],
          "ShouldMatchAll" : "false"
        }
      }
    }
  }
}
...

📘

Note

For EpiServer.CMS version 12.18.10 or higher, you need to add CmsPolicy like in the following code.
See remarks in Class CmsPolicyOptions.

...
"EpiServer" : {
  "Cms" : {
    "CmsPolicy": {
       "EditRoles": [ "SearchAdmins", "WebEditors", "WebAdmins",... ],
       "DefaultShellModuleRoles": [ "SearchAdmins", "WebEditors", "WebAdmins",... ]
    }
  }
}
...

Register virtual roles programmatically

You can register virtual roles programmatically:

using EPiServer.Security;
using EPiServer.DependencyInjection;
using EPiServer.ServiceLocation;
    
public class Startup
{
  ...
  public void ConfigureServices(IServiceCollection services)
  {
    ...
    services.AddVirtualRole<MyVirtualRoleType>("MyVirtualRoleType");
  }
  ...
}

Login for Virtual Roles

After creating new Virtual Roles and adding to Access Rights > Administer Users, some Virtual Roles do not have full access to your Cms Admin, so use the correct link to login like /Episerver/CMS or Episerver/Find for each role permission.