Configuring EPiServer CMS 5 to Use Active Directory Membership Provider

Introduction

This technical note describes how to use Active Directory for authorization and authentication together with EPiServer CMS 5.

Table of Contents

• Active Directory Membership Provider
• Compile the Active Directory Role Provider
• Configure EPiServer CMS 5 to Use Active Directory Membership Provider
• Configure EPiServer CMS 5 to USe Active Directory Role Provider

Active Directory Membership Provider

There is an Active Directory membership provider in the .NET 2.0 Framework which we will use, and EPiServer CMS 5 now also provides its own Active Directory role provider

Note: The Active Directory role provider is currently distributed as source code. You need to include the source code in your EPiServer project (see instructions below) and compile it. Note that the current version is subject to change. The following release, EPiServer CMS 5 R2 will contain the provider and from that version on there will be no need to download the provider separately.

Requirements

• A Windows ActiveDirectory domain.
• A Web server running EPiServer CMS 5

Note: The Web server with EPiServer CMS 5 does not have to be a member of the Active Directory domain, it will simply use a configured service account to communicate with the Active Directory domain controller. 

Compile the Active Directory role provider

The file that you downloaded from www.episerver.com contains a Source folder with the following files:

Include all these files in your current solution, for example if you are developing your EPiServer site based on the Public templates package, do the following:

1. Open the EPiServer.Templates.Public.csproj project file with Microsoft Visual Studio.
2. If you do not have references to the System.DirectoryServices assembly already set up in your project, you will need to add it.
3. Create a new folder named “Security” in the project.
4. Add the four files listed above to the Security folder.
5. Build the solution.

Configure EPiServer CMS 5 to Use Active Directory Membership Provider

To configure your site, add the following to the <membership><providers> section of web.config:

Modify the connectionUsername and connectionPassword and insert values for a user account with appropriate privileges. See the documentation for the class ActiveDirectoryMembershipProvider for details on security issues.

Basically any authenticated user account will have the necessary permissions (the Authenticated Users group in its default configuration will give the appropriate permissions). If your Active Directory has been reconfigured and has had the default permissions changed, you have to make sure that the account has the following permissions to all groups and users that are part of the subtree that the connection string refers to:

You should also add a connection string to the <connectionStrings> section that defines how the membership provider will connect to the ActiveDirectory.

An example:

Once again, see documentation for the class ActiveDirectoryMembershipProvider for details on the connection string and configuration parameters.

If you create a new user in an Active Directory domain, you will actually have two different user names:

Note: 

Important:

If you decide to switch the type of user name, you will loose all profile information for the users and any user specifc access rights that has been set (access rights assigned at the group level will remain intact).

If you need to troubleshoot the LDAP connection with a network monitor you might want to enable unsecure communication with the Active Directory server to see the communication in clear text. Enable unsecure communication by adding the attribute connectionProtection="None".

Configure EPiServer to Use Active Directory Role Provider

To configure your site, add the following to the <roleManager><providers> section of web.config:

Note: The required attributes shown above are identical to the attributes for the Active Directory membership provider. This is intentional, in most cases you can and should use the same AD account and connection string for both the membership and role providers.

Modify the “name of assembly” of the type attribute – this should be the name of the assembly created by the project where you included the Active Directory Role provider source code. For the example of the Public templates package shown above, it should be EPiServer.Templates.Public.

Modify the connectionUsername and connectionPassword and insert values for a user account with appropriate privileges.

The role names used by default are the Windows domain compatible names (shown below as pre-Windows 2000 group name). You can use the attribute attributeMapRolename to choose some other attribute for role name if you want to. Some possibilities are "cn" (which will be the Group name as shown below) or "distinguishedName" (which will be the fully qualified name such as CN=EPiServerUsers,DC=domain,DC=mycompany,DC=local). The default value is "sAMAccountName".

To be compatible with the Active Directory membership provider, the default user name mapping is the user principal name, i.e. user names in the form "user@mycomapny.domain.local". To change it into the standard Windows user name, add the attribute attributeMapUsername="sAMAccountName".

For troubleshooting purposes we support the connectionProtection attribute. Set connectionProtection="None" for clear-text authentication and communication.

The Active Directory data is aggressively cached by the role provider. You can control the cache expiration with the attribute cacheTimeout. For example setting cacheTimeout="1:30:0" sets the timeout to 1 hour 30 minutes. The default is 10 minutes.