November Happy Hour will be moved to Thursday December 5th.

AI OnAI Off

Using the Authorization Manager for Handling Roles in EPiServer CMS 5

Product version:

EPiServer CMS 5 R2 SP1

Document version:

1.0

Document last saved:

Introduction

This technical note describes how to use the Authorization Manager (frequently referred to as AzMan) together with EPiServer CMS.

This tech note uses the Active Directory authorization store type as an example, but if you want to use plain Acitive Directory we recommend using the ActiveDirectory Membership and Role providers. Authorization Manager is the preferred option only if you have complex business rules for your authorization handling, since it has a much higher overhead, both in terms of configuration and performance.

Table of Contents

Introduction to AzMan

From a .NET viewpoint you will simply use the AuthorizationStoreRoleProvider which is fairly easy to set up. The complex part is AzMan itself and the underlying infrastructure. You should carefully evaluate your authorization needs and only use AzMan if you need the advanced features and administration support that AzMan provides.

Note: One feature of AzMan is the possibility to dynamically evaluate role memberships based on scripts. This feature can be implemented in EPiServer CMS by using virtual roles. See the separate tech note on this subject.

There is plenty of information concerning AzMan and using the XML file authorization store, so we will not cover that configuration, but instead focus on using ActiveDirectory as the authorization store.

For more information on AzMan, see

» http://www.microsoft.com/technet/prodtechnol/windowsserver2003/technologies/management/athmanwp.mspx - General information.

» http://msdn2.microsoft.com/en-us/library/Aa480244.aspx - Comprehensive white paper for developers.

» http://blogs.msdn.com/azman/ - AzMan blogs. 

Requirements

  • A Windows ActiveDirectory domain.
    Note: If you are running the domain controller in Windows 2000 mixed mode, you have to raise the domain functionality level to Windows 2003 mode. See details below.
  • The web server running EPiServer CMS must be a member of the Active Directory domain.
  • Authorization manager must be installed on the web server. It is installed by default on a Windows Server 2003.

Set Up Authorization Manager and the Authorization Store

If running on Windows XP, install the Windows Server 2003 Administration Pack, which contains AzMan, from

» http://www.microsoft.com/downloads/details.aspx?familyid=c16ae515-c8f4-47ef-a1e4-a8dcbacff8e3&displaylang=enStart 

  1. Start the AzMan administration interface by running azman.msc (can be found in the Windows\System32 folder).

    2.  

  2. Switch to Developer Mode by right-clicking the Authorization Manager node and select Options.

    3.  

  3. Create a new Authorization Store by right-clicking the Authorization manager node again and select New Authorization Store.

    4.  

    Note: If your Active Directory domain is running in Windows 2000 mixed mode you will receive the following message.

    To proceed you need to go to Windows 2003 functionality level.

  4. You now have an EPiServer node under Authorization Manager. Right-click on this node and select New Application...

  5. After adding the application you will see the following view and the basic configuration of AzMan is done.

Role Definitions

In order to make AzMan do anything useful you need to define one or more roles and then assign the roles.

  1. Initially we recommend that you create the WebAdmins and WebEditors roles, since these roles are predefined in the default web.config file installed with EPiServer CMS.

  2. This gives you two role definitions, but the roles are still not accessible from EPiServer CMS, since only roles listed under Role Assignments will be visible to the Authorization store role provider. Right click on Role Assignments and select Assign Roles...

  3. Check all the roles that you want to expose and click OK.
  4. Now you need to define the actual criteria for determining role membership. The simplest way to do this is to assign a Windows group to the role. Right click on the role under Role Assignments and select Assign Windows Users and Groups...

  5. Enter the groups and/or users that should belong to the role and click OK.

Access to AzMan

You need to define the groups / users that have access to AzMan in order for external systems such as EPiServer to be able to connect to AzMan and use its authorization features. This is configured by right-clicking the EPiServer authorization store and selecting Properties.

Select the Security tab and select the Reader user role from the drop down:



If you are running on a Windows Server 2003, add the IIS_WPG group to the list of readers, if running under Windows XP, add the ASPNET account to the Readers role.

Other AzMan Features

There are a lot of capabilities in AzMan that we have not discussed, such as defining roles from sub-roles and tasks, determining role membership by LDAP queries, determining role membership with scripts etc. These are Azman specific features and does not affect the EPiServer connection.

Configure EPiServer to use Authorization Manager

First you need to configure EPiServer to use a suitable membership provider. With the ActiveDirectory scenario that we are discussing, the ActiveDirectoryMembershipProvider should be used.

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

<add name="ActiveDirectoryMembershipProvider"
     type="System.Web.Security.ActiveDirectoryMembershipProvider, System.Web, 
      Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a"
     connectionStringName="ActiveDirectoryMembershipProviderConnection"
     connectionUsername="Some AD account with read access to AD"
     connectionPassword="Password for AD account"
     enableSearchMethods="true" /> 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.

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

<add name="ActiveDirectoryMembershipProviderConnection"
     connectionString="LDAP://domain.mycompany.local" />Once again, see documentation for the class ActiveDirectorymembershipProvider for details on the connection string and configuration parameters.

Now we are ready to add the AuthorizationStoreRoleProvider which is the actual connection to AzMan. Add the following to the <roleManager><providers> section:

<add name="AuthorizationStoreRoleProvider"
     type="System.Web.Security.AuthorizationStoreRoleProvider, System.Web, 
     Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a"
     connectionStringName="AuthorizationServices"
     applicationName="EPiServer Application"
     cacheRefreshInterval="1"
     scopeName="" />Note: The applicationName should match the name entered when creating the application in AzMan (see above).

You should also add a connection string to the <connectionStrings> section. An example:

<add name="AuthorizationServices" 
     connectionString="msldap://servername/CN=EPiServer,CN=Program Data,
        DC=domain,DC=mycompany,DC=local" />

See the developer documentation for AutorizationStoreRoleProvider class for details on the connection string and provider parameters.

You should now be ready to test your application in an ActiveDirectory environment.