---
title: Virtual roles
slug: cms-13/docs/virtual-roles
docTags: 
createdAt: 2026-07-30T20:22:03.890Z
---

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.

:::hint{type="info"}
**Note**
`ShouldMatchAll` defaults to `false`.
:::

The following example configures `MappedRoles` in `appsettings.json`:

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

:::hint{type="info"}
**Note**
For `EPiServer.CMS` version 12.18.10 or higher, add `CmsPolicy` configuration as shown in the following code.
See remarks in [Class CmsPolicyOptions](https://world.optimizely.com/csclasslibraries/cms/EPiServer.Authorization.CmsPolicyOptions?version=12).
:::

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

## Register virtual roles programmatically

Register virtual roles in the `Startup` class using `AddVirtualRole`:

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