EPiServer CMS 5 R2
Document last saved:
The authentication and authorization system in EPiServer CMS uses the default membership and role system as introduced in ASP.NET 2.0. See Scott Guthrie's blog for some background information: ASP.NET 2.0 Membership, Roles, Forms Authentication, and Security Resources. For more details on the provider model, see the "Introduction to the Provider Model" section on the following page: http://msdn2.microsoft.com/en-us/asp.net/aa336558.aspx.
Configuration of membership and role providers is done with web.config. Note that if you change providers, you may have to revise the security settings (ACLs) for your entire site, since it is highly likely that user names and role names changes when you switch providers.
An example Web.Config section:
<roleManager enabled="true" defaultProvider="WindowsRoleProvider">
type="EPiServer.Security.WindowsRoleProvider, EPiServer" />
System.Web, Version=126.96.36.199, Culture=neutral,
Version=188.8.131.52, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a"
The <membership> section controls the membership provider to use. Note that even though there are three providers listed in the <providers> section, only one is active at this time - the WindowsMembershipProvder (controlled by the defaultProvider attribute of the <membership> tag). I.e. the <add ...> lines for MultiplexingMembershipProvider and SqlServerMembershipProvider could be removed without affecting the functionality. There is one exception to this statement - if you have selected the MultiplexingMembershipProvider as the default provider, it will make use of additional providers as defined by the provider<n> attributes.
Similarily the <roleManager> section controls the role provider to use. The same basic principles of defaultProvider / Multiplexing provider as for membership applies here as well.
When you select the provider to use you are deciding which user database that EPiServer CMS authenticates its users against. As previously stated, it is possible to change the provider at any time, but this may cause problems forcing you to revise the security settings in EPiServer CMS.
Also note that the membership and role providers are configured separately, but a specific membership provider may require a certain role provider and vice versa. For the current set of providers you must have matching role and membership providers, i.e. if you decide to use WindowsMembershipProvider you must use the WindowsRoleProvider.
When you administer access rights to pages in EPiServer CMS, you use three distinct components that are tied very loosely together. This will cause the UI to show information that may appear confusing. The three components are:
An ACL is simply a list of SecurityEntities and an access level. The security entity is a name and information stating if the name represents a role or a user. Once you have a security entity in an ACL, it will not be affected by changes in the membership or role provider. One aspect of this is that when you delete a role and then look at an ACL that had an access entry for this role, the role will still be displayed in the ACL.
Membership providers have APIs for creating, editing and deleting users, but not all providers support updates of the user database. The SQL membership provider allows you to modify the user database, but the Windows membership provider does not. This will be reflected in the UI when you browse users.
Note: If you are using the Multiplexing membership provider and want to create users, then the first provider in the multiplexing list (provider1) must support it. The same applies for role providers.
EPiServer CMS 5 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 web.config. A typical configuration looks like this:
type="EPiServer.Security.WindowsAdministratorsRole, EPiServer" />
type="EPiServer.Security.EveryoneRole, EPiServer" />
type="EPiServer.Security.AuthenticatedRole, EPiServer" />
type="EPiServer.Security.AnonymousRole, EPiServer" />
type="EPiServer.Security.CreatorRole, EPiServer" />
The EPiServer.Configuration.VirtualRolesElement.ReplacePrincipal attribute controls wether 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 , 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.
We deliver five virtual roles with EPiServer CMS:
In addition to the precreated 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 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 two 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, for example in Swedish Windows versions, the Administrators group is named "Administratörer". The Administrators virtual role will do 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 it will return true if the current principal is the same as the Creator for an ACL.
If you are running in an Enterprise configuration and have a web.config file with multiple site definitions, there are some security-related issues you should be aware of.
The membership and role provider definitions cannot be configured on a per-site basis. If you must have separate provider definitions for each site, you cannot share the web.config file. This is a restriction in the Microsoft implementation of ASP.NET 2.0 and not a restrinction in EPiServer CMS 5.
If you are using the SQL Server membership / role provider and want to use the same set of users / roles for all sites using the same web.config files (probably the most common scenario), you need to use a separate database for the user / role information.