Virtual roles

Virtual roles extend the standard role concept in CMS 13 by evaluating membership at runtime instead of storing it in the database. Use virtual roles to grant access based on dynamic criteria that vary with each request, such as business hours or combined group membership.

Add virtual roles to claims with the SupportsClaims property. By default, SupportsClaims controls whether CMS adds a claim to the current principal for each virtual role the user belongs to.

Access the current principal with EPiServer.Security.PrincipalInfo.CurrentPrincipal (recommended). Alternate approaches such as System.Web.HttpContext.Current.User are also supported.

When SupportsClaims="false" on a virtual role, CMS evaluates the role only during access control list (ACL) checks. Any principal.IsInRole call for that virtual role returns false.

The following virtual roles are included with CMS:

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

In addition to the predefined roles, create custom virtual roles to grant access based on business rules, such as restricting access to business hours. A common scenario is defining a virtual role that evaluates to true when a user belongs to both role1 and role2. This approach reduces the number of groups needed.

The following list describes the predefined virtual roles:

• Administrator – Runs a localization-independent test for the Administrators group. This supports localized Windows versions where the Administrators group name is translated. It eliminates the need to modify web.config or access rights in CMS.
• Creator – Evaluates to true when the current principal matches the creator of a content item in an AccessControlList. Used only during ACL evaluation.
• PackagingAdmins – Controls access to the Add-ons menu where apps are managed.
• SearchAdmins – Controls access to the Optimizely Search & Navigation UI and the Clear Indexes page. Non-administrator users of Search & Navigation must hold both the WebEditors and SearchAdmins roles.
• SearchEditors – Controls access to the Optimizely Search & Navigation UI. SearchEditors cannot execute the Clear Indexes action.

The PackagingAdmins, CmsAdmins, CmsEditors, SearchEditors, and SearchAdmins virtual roles use the MappedRole type, which maps groups to other groups. The roles attribute contains one or more role names used to evaluate membership. The ShouldMatchAll property controls matching behavior:

• false – Membership in at least one listed role grants membership in the mapped role.
• true – Membership in all listed roles is required for membership in the mapped role.

📘

Note

ShouldMatchAll defaults to false.

The following example configures MappedRoles in appsettings.json:

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

📘

Note

For EPiServer.CMS version 12.18.10 or higher, add CmsPolicy configuration as shown in the following code. See remarks in Class CmsPolicyOptions.

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

Register virtual roles programmatically

Register virtual roles in the Startup class using AddVirtualRole:

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

Log in for virtual roles

After you create virtual roles and add them in Settings > Administer Users, certain virtual roles may lack full access to CmsAdmin. Use the correct URL for each role permission, such as /Episerver/CMS or /Episerver/Find.