---
title: Virtual roles
slug: cms-12/docs/virtual-roles
docTags: 
createdAt: 2026-08-10T15:55:57.000Z
---

Optimizely Content Management System (CMS) uses an extension of the Role concept called **Virtual Roles**. These are roles where the membership criteria are 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 a user is a member.

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

If `SupportsClaims="false"` on the virtual role, 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
- Everyone
- Authenticated
- Creator
- CmsAdmins
- CmsEditors
- SearchAdmins
- SearchEditors

In addition to the predefined roles, you can create 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.

- **Creator** – Only used when evaluating `AccessControlLists` in CMS and returns true if the current principal is the same as the Creator for an ACL.
- **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 WebEditors *and* SearchAdmins: WebEditors to access the edit view and SearchAdmins to access Optimizely Find features.
- **SearchEditors** – Control access to the Optimizely Search & Navigation user interface. SearchEditors cannot execute the Clear Indexes action

The **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 has 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 the roles listed in the roles attribute is required for membership in the mapped role.

:::hint{type="info"}
**Note**
**ShouldMatchAll** will default to **false** if not set.
:::

Example of Mapped Roles in `appsettings.json`:

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

:::hint{type="info"}
**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](https://world.optimizely.com/csclasslibraries/cms/EPiServer.Authorization.CmsPolicyOptions?version=12).
:::

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

## Register virtual roles programmatically

You can register virtual roles programmatically:

```csharp
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 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.