Virtual roles

Episerver 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.

How it works

Virtual roles are controlled by the <virtualRoles> configuration element in the <episever.framework> section in web.config. A typical configuration looks like this:

<virtualRoles addClaims="true">
   <providers>
      <add name="Administrators" type="EPiServer.Security.WindowsAdministratorsRole, EPiServer" />
      <add name="Everyone" type="EPiServer.Security.EveryoneRole, EPiServer" />
      <add name="Authenticated" type="EPiServer.Security.AuthenticatedRole, EPiServer" />
      <add name="Anonymous" type="EPiServer.Security.AnonymousRole, EPiServer" />
      <add name="PackagingAdmins" type="EPiServer.Security.MappedRole, EPiServer.Framework" roles="WebAdmins, Administrators" mode="Any" />
      <add name="CmsAdmins" type="EPiServer.Security.MappedRole, EPiServer" roles="WebAdmins, Administrators" mode="Any" />
      <add name="CmsEditors" type="EPiServer.Security.MappedRole, EPiServer" roles="WebEditors" mode="Any" />
      <add name="Creator" type="EPiServer.Security.CreatorRole, EPiServer" />
      <add name="SearchAdmins" type="EPiServer.Security.MappedRole, EPiServer.Framework" roles="WebAdmins, Administrators" mode="Any" /> 
  </providers>
</virtualRoles>

Virtual roles can operate in two modes. By default, the addClaims attribute sets whether a claim is added to the current principal for each virtual role in which a user is member. If you set replacePrincipal to true, then the principal object gets replaced with a principal object wrapper that supports virtual roles by overriding the IsInRole method. This mode is not supported with federated security or other scenarios where claims are used because the wrapper is not claims-aware.

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 both replacePrincipal="false" and addClaims="false" then virtual roles are only evaluated when you check access rights based on ACLs in Episerver CMS. Any principal.IsInRole calls for a virtual role returns false.

The <providers> element contains a series of <add...> tags. Each <add...> defines a virtual role implementation (as identified by the type attribute) and gives the role a name with the name attribute.

The following virtual roles are delivered with Episerver CMS:

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

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 Episerver CMS.

• Administrator is 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 Episerver CMS
• Creator is only used when evaluating AccessControlLists in Episerver CMS and returns true if the current principal is the same as the Creator for an ACL.
• PackagingAdmins is used for controlling access to the Add-ons menu option from where add-ons are managed.
• SearchAdmins is used for controlling access to the Episerver Find user interface. Note that Episerver Find users that are not Administrators need to be both WebEditors and SearchAdmins. WebEditors to access the Episerver edit view and SearchAdmins to access Episerver Find features.

The PackagingAdmins, CmsAdmins, CmsEditors 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. The mode attribute can have the following values:

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

Registering virtual roles programmatically

You can register virtual roles programmatically:

[InitializableModule]
[ModuleDependency((typeof(EPiServer.Web.InitializationModule)))]
public class VirtualRoleInitializer : IInitializableModule
{
    public void Initialize(InitializationEngine context)
    {
        var virtualRoleRepository = VirtualRoleRepository<VirtualRoleProviderBase>.GetDefault();
        virtualRoleRepository.Register("MyVirtualRoleType", new MyVirtualRoleType());
    }

    public void Uninitialize(InitializationEngine context) { }
    public void Preload(string[] parameters) { }
}