This content is archived. See latest version here

Last updated: Mar 25 2013

EPiServer CMS uses an extension of the Role concept called Virtual Roles. These are roles where the membership criteria is determined at runtime for each call to IsInRole. In other words, the virtual role membership is not stored in the database, but depends on programmatic criteria.

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

XML
<virtualRoles replacePrincipal="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="Creator"
         type="EPiServer.Security.CreatorRole, EPiServer" />
      <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" />
  </providers>
</virtualRoles>

The EPiServer.Configuration.VirtualRolesElement.ReplacePrincipal attribute controls whether the current principal object gets replaced with a principal object wrapper that also supports virtual roles. The current principal object can be accessed in several different ways. The recommended approach is to use EPiServer.Security.PrincipalInfo.CurrentPrincipal property, but alternate ways such as System.Web.HttpContext.Current.User are also supported.

If replacePrincipal="false", virtual roles will only be evaluated when checking access rights based on ACLs in EPiServer CMS. Any principal.IsInRole calls for a virtual role will return false.

The <providers> section 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

In addition to the predefined roles, it is very easy to create new virtual roles to allow access based on business rules, such as only allow access 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. This can be used to reduce the number of groups needed for setting the required permissions in EPiServer CMS.

The built-in virtual roles are fairly self-explanatory. The few that may require a bit more in-depth explanation are Administrator and Creator.

Administrator is needed to support localized versions of Windows, where the Administrators group has been translated. The Administrators virtual role will do a localization-independent test for the Administrators group, thus eliminating the need to manually modify episerver.config or access rights in EPiServer CMS

Creator is only used when evaluating AccessControlLists in EPiServer CMS and it will return true if the current principal is the same as the Creator for an ACL.

The CmsAdmins and CmsEditors virtual roles are of the MappedRole type (MappedRole is 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.

Do you have feedback on this documentation? Send an email to documentation@episerver.com. For development-related questions and discussions, refer to our Forums on https://world.episerver.com/forum/