How To: Use ADAM for Roles in ASP.NET 2.0

patterns & practices Developer Center

J.D. Meier, Alex Mackman, Blaine Wastell, Prashant Bansode, Andy Wigley, Kishore Gopalan

Microsoft Corporation

August 2005

Applies To

• ASP.NET version 2.0
• Active Directory Application Mode (ADAM)
• Microsoft Windows Server™ 2003 operating system or Microsoft Windows® XP Professional SP1 or later operating system

Summary

This How To shows you how you can develop an ASP.NET Web site that uses Active Directory Application Mode (ADAM) to store ASP.NET roles. It shows you how to configure ADAM and the Authorization Manager (AzMan) policy store, how to create new roles and add a user to a role, and how to use the Roles Management API for roles-based authorization. Using ADAM as a roles store is a good solution for applications accessed over an intranet or extranet where the user accounts store is Microsoft Active Directory® directory service or ADAM and where the application requires application-specific roles that are different from Active Directory groups.

Contents

Objectives
Overview
Installation Requirements
Summary of Steps
Step 1. Install the ADAM Instance
Step 2. Configure the AzMan Policy Store in ADAM
Step 3. Configure the Web Application to Use the AuthorizationStoreRoleProvider
Step 4. Perform Role Management Operations
Additional Considerations
Additional Resources

Objectives

• Use ADAM for role storage.
• Create an Authorization Manager policy store in ADAM.
• Configure the AuthorizationStoreRoleProvider.
• Perform role checks within an ASP.NET application.

Overview

The Roles Management API in ASP.NET version 2.0 allows you to implement application-specific roles and manage user role membership. To achieve this, the Roles Management system stores its data in an underlying data store that it accesses through an appropriate role provider for that data store. Supported role providers include SqlRoleProvider, WindowsTokenRoleProvider, and AuthorizationStoreRoleProvider. All of these implement a standard set of role provider interfaces.

You can use an AzMan policy store in ADAM to store role data that is specific to an application or Web site (such as what roles a user belongs to), while keeping that data separate from the generic user information (such as full name and Windows group membership), which is stored in a domain's Active Directory. When a user logs on to a Web site running ADAM, the site authenticates the user with the Active Directory user store, and then uses the AuthorizationStoreRoleProvider to read which roles the user belongs to from the application roles that are kept in the AzMan policy store in ADAM. The ASP.NET application and the ADAM instance do not have to be on the same server.

When you use role-based authorization, your application must authenticate its users. You can use any available form of authentication, such as Windows authentication or forms authentication. If you use forms authentication and you want to use the AuthorizationStoreRoleProvider, your users must have valid Windows local or domain user accounts. You can use the ASP.NET role management feature independently or in conjunction with the ASP.NET membership feature.

This How To shows you how to set up ADAM on a server and how to configure an AzMan policy store in ADAM. It shows you how to create a Web site that uses Windows authentication to identify users and then uses the AuthorizationStoreRoleProvider role provider (which uses the AzMan policy store in ADAM) to provide role management for users of that Web site. Additionally, it shows you how to create roles and add users to those roles programmatically.

The ASP.NET AuthorizationStoreRoleProvider uses only the AzMan functionality that is necessary to support the functionality implemented in the ASP.NET role management API. AzMan supports additional role management functionality that you can access by using the AzMan APIs. For more information, see How To: Use Authorization Manager (AZMan) with ASP.NET 2.0.

Installation Requirements

You can install and run ADAM on any computer that uses the Microsoft Windows Server™ 2003 or Windows® XP Professional SP1 or later operating systems. You can download ADAM from: https://www.microsoft.com/downloads/details.aspx?FamilyID=9688f8b9-1034-4ef6-a3e5-2a2a57b5c8e4&DisplayLang=en.

AzMan is available for Windows Server 2003, Windows XP Professional, and Windows 2000 Server as follows:

• Windows Server 2003: Install Windows 2003 Server Service Pack 1 or later. You can install this from https://windowsupdate.microsoft.com.

• Windows XP Professional: Install the Windows Server 2003 Administration Tools Pack, which is available for download at https://www.microsoft.com/downloads/en/default.aspx. This tools pack allows remote server management of Windows Server 2003 and also includes AzMan.

  Note   If you are running Windows XP Service Pack 2 or later, you must install Service Pack 1 or later of the Windows Server 2003 Administration Tools Pack.

• Windows 2000: Download the Windows 2000 Authorization Manager Runtime available at https://www.microsoft.com/downloads/details.aspx?FamilyID=7edde11f-bcea-4773-a292-84525f23baf7&DisplayLang=en. Your computer must have Windows 2000 Server Service Pack 4 or later installed. You must also install MSXML 4.0 Service Pack 2 or later.

  This installs the run-time components only and not the AzMan administration Microsoft Management Console (MMC) snap-in. You can still use the MMC snap-in on a computer that uses Windows Server 2003 or on a computer that uses Windows XP and has the Windows Server 2003 Administration Tools Pack installed, to remotely administer AzMan on a computer running Windows 2000 Server.

Summary of Steps

Follow these steps to use ADAM for roles in ASP.NET 2.0 applications:

• Step 1. Install the ADAM instance.
• Step 2. Configure the AzMan policy store in ADAM.
• Step 3. Configure the Web application to use the AuthorizationStoreRoleProvider.
• Step 4. Perform role management operations.

Step 1. Install the ADAM Instance

In this step, you install the ADAM instance to be used as the role store for your application. You do not need to install the ADAM instance on the same computer as your ASP.NET application.

To install an ADAM instance

1. Log on to your computer by using an account in the Administrators group.

2. Download the ADAM installer from https://www.microsoft.com/downloads/details.aspx?FamilyID=9688f8b9-1034-4ef6-a3e5-2a2a57b5c8e4&DisplayLang=en. Run the installer, which unzips the product files into a directory of your choice.

3. Go to the directory where you extracted the ADAM files, and run ADAMSetup.exe to start the setup. A wizard will guide you through most of the subsequent steps.

4. After you accept the license agreement, on the Installation Options page, select ADAM and ADAM administration tools.

5. In Setup Options, select A unique instance.

6. Type the name you want to use for this ADAM instance. For this example, use AdamForRolesProvider.

   Note   Create a name that is meaningful for your application. The ADAM instance name is used as the name of the service and also as the default location for the ADAM data store.

7. On the Ports page, accept the defaults and make a note of the port numbers. You will need this information in subsequent steps.

   Note   If you install ADAM on a computer that has either of the default ports in use, the ADAM setup wizard automatically locates the first available port, starting at 50000. For example, Active Directory uses ports 389 and 636, as well as ports 3268 and 3269 on global catalog servers. Therefore, if you install ADAM on a domain controller, the ADAM setup wizard provides a default value of 50000 for the LDAP port and 50001 for the SSL port.

8. On the Application Directory Partition page, select Yes create an application directory partition and type a partition name. For this example, use the partition name OU=SecNetPartition,O=SecNet,C=US.

9. On the File Locations page, type the location where the ADAM system files are installed. In this example, accept the defaults.

10. Under Service Account Selection, use the default Network service account. If your Windows Server 2003 computer is not a member of a domain, you will see a warning message concerning replication. Click Yes to continue.

    Note   The account that you select determines the security context in which the ADAM instance runs. Unless you are installing ADAM on a domain controller, the ADAM setup wizard defaults to the Network Service account. When you install ADAM on a domain controller, you must select a domain user account as the ADAM service account.

11. You must be sure that the local security policy does not prevent local users who connect over the network from authenticating as themselves. Otherwise, users who connect to ADAM over the network are forced to use a security context of Guest, and any attempts to bind to ADAM will fail.

    To check this, leave the ADAM setup wizard running and do the following:

    1. On the Start menu, click Control Panel.
    2. Open Administrative Tools, and then double-click the Local Security Policy option.
    3. Under Security Settings, expand Local Policies, then select Security Options.
    4. In the Policy list, double-click Network Access: Sharing and Security model for local accounts.
    5. Set this to Classic–local users authenticate as themselves, and then click OK.

12. Return to the ADAM Setup Wizard. On the ADAM Administrators page, select This account, and then specify the local group, Administrators.

13. On the Importing LDIF Files page, select Import the selected LDIF files for this instance of ADAM, and then add the following LDIF files:

    • MS-AZMan.LDF
    • MS-InetOrgPerson.LDF
    • MS-User.LDF

    After you add the files, click Next.

    Note   LDIF files are schema files for special objects in ADAM. The AzMan.LDF file is the schema for AzMan.

14. On the Ready to install page, click Next to start the installation.

Step 2. Configure the AzMan Policy Store in ADAM

In this step, you configure the AzMan Policy Store in ADAM. To configure the AzMan policy store, do the following:

• Set up the AzMan policy store in ADAM.
• Assign the Network Services account the administrator role in AzMan.
• Create an AzMan application.

To create the AzMan policy store in ADAM

1. At the command prompt, type azman.msc to open the Authorization Manager snap-in.

2. On the Action menu, click Options, and then click Developer mode.

3. On the Action menu, click New Authorization Store. Set the Authorization store type as Active Directory. Type the following Store name, leave the description field blank, and then click OK.

   msldap:// servername**:** portnumber**/CN=AzManADAMStore,** partition

   In the command above:

   • Change servername to the name of your server or to localhost to administer the instance on the local computer.
   • Change portnumber to the port number you used when you set up the ADAM instance.
   • Change partition to the partition name that you created when you installed ADAM. If you used the suggested name in Step 1, this would be OU=SecNetPartition,O=SecNet,C=US.
   • The container name for your AzMan policy store in ADAM is CN=AzManADAMStore. You can change this to something else if you prefer.

4. Right-click the AzManADAMStore, and then click Properties. In the Properties window, click the Security tab.

5. Under Authorization Manager user role, choose the required access level from the following options:

   • Administrator. The user can do full role management and perform access checks.
   • Reader. The user can read the store and perform access checks.
   • Delegated User. When combined with the Administrator setting, this allows the user to audit applications and scopes. See Authorization auditing in Authorization Manager Help for details.

   For the purposes of this How To, select Administrator. Click the Add button to add the account that ASP.NET uses (the Network Service account) to this role.

   Note   If your ASP.NET application uses impersonation to impersonate a fixed identity or if you have configured your ASP.NET application to run under a custom account, you must add the impersonated account or custom account as an Administrator or Reader, according to the level of access required.

To create the AzMan application

1. Make sure that the AzManAdamStore is selected in the console tree. In the Actions menu, click New Application.
2. Type a name for your application. For this example, use AzManDemo and leave the Description and Version Info fields blank.

Step 3. Configure the Web Application to Use the AuthorizationStoreRoleProvider

In this step, you configure ASP.NET to use the AuthorizationStoreRoleProvider, which is used to connect to the AzMan policy store in the ADAM instance that you just created. See "Additional Considerations" for instructions on using the AuthorizationStoreRoleProvider with Windows XP or Windows 2000.

To create an ASP.NET application and configure it to use the AuthorizationStoreRoleProvider

1. Create an empty Web site project and add a connection string for the AzMan policy store in ADAM to the Web.config file by using the following steps:

   1. Create a new empty ASP.NET Web site, and name it AdamRoles.

   2. Add a Web.config file to your project.

   3. Define a connection string to the AzMan policy store in ADAM in the <ConnectionStrings> element. The connection string takes the following format.

      msldap:// servername:port/CN=container, partition
      

      Using the example, add the following connection string:

      <add name="AzManADAMServer" connectionString=
      "msldap://servername:port/CN=AzManADAMStore,OU=SecNetPartition,O=SecNet,C=US"/>
      
      

      Where servername is your server name and port is your port number.

2. Configure the application to use the role provider by adding the following elements as children of the <system.web> element.

   <roleManager 
       enabled="true" 
       cacheRolesInCookie="true" 
       defaultProvider="RoleManagerAzManADAMProvider"
       cookieName=".ASPXROLES" 
       cookiePath="/" 
       cookieTimeout="30" 
       cookieRequireSSL="true" 
       cookieSlidingExpiration="true"
       createPersistentCookie="false" 
       cookieProtection="All">
       <providers>
           <add name="RoleManagerAzManADAMProvider"
        type="System.Web.Security.AuthorizationStoreRoleProvider, System.Web, Version=2.0.0.0, Culture=neutral, 
                publicKeyToken=b03f5f7f11d50a3a"
                connectionStringName="AzManADAMServer" 
                applicationName="AzManDemo"/>
       </providers>
   </roleManager>
   
   

Note   By ensuring unique values for the cookieName and cookiePath attributes, you prevent possible problems that can occur when hosting multiple applications on the same server. This best practice will prevent a user on one site from using his or her role cookie on a different site hosted on the same server.

Step 4. Perform Role Management Operations

In this step, you create a test application that assigns a role to a user, removes a role from a user, and tests for role membership. The data that supports these role management operations is stored in the AzMan store in ADAM.

To test role management

1. Add a WebForm called Default.aspx to the Web site that contains the following code.

   <%@ Page Language="C#" %>
   
   <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
   
   <script >
   
       protected void Page_Load(object sender, EventArgs e)
       {
           if (!Roles.RoleExists("TestRole"))
           {
               Roles.CreateRole("TestRole");
           }
   
           ShowRoleMembership();
       }
   
       private void ShowRoleMembership()
       {
           if (Roles.IsUserInRole("TestRole"))
           {
               Label1.Text = User.Identity.Name + " is in role TestRole";
           }
           else
           {
               Label1.Text = User.Identity.Name + " is NOT in role TestRole";
           }
       }
   
       protected void Button1_Click(object sender, EventArgs e)
       {
           Roles.AddUserToRole(User.Identity.Name, "TestRole");
           ShowRoleMembership();
       }
   
       protected void Button2_Click(object sender, EventArgs e)
       {
           Roles.RemoveUserFromRole(User.Identity.Name, "TestRole");
           ShowRoleMembership();
       }
   </script>
   
   <html xmlns="http://www.w3.org/1999/xhtml" >
   <head >
       <title>Untitled Page</title>
   </head>
   <body>
       <form id="form1" >
       <div>
           <asp:Button ID="Button1"  Text="Add to role" 
                       OnClick="Button1_Click" /><br />
           <br />
           <asp:Button ID="Button2"  Text="Remove from role" 
                       OnClick="Button2_Click" /><br />
           <br />
           <asp:Label ID="Label1"               
                      Text="Label">
           </asp:Label>
       </div>
       </form>
   </body>
   </html>
   
   

2. Run the application. Note the following features about this application:

   1. When you start it up, the code in the Page_Load event handler creates the role TestRole, if it does not already exist.

   2. The text of Label1 shows whether or not the current authenticated user is a member of the TestRole role.

   3. When you click the Add to role button, the code in the Button1_Click event handler uses the Roles API to add the current authenticated user to the TestRole role.

   4. If you click the Add to role button again before clicking the Remove from role button, the call to Roles.AddUserToRole throws an exception because the user is already in the role TestUser. You must code for this condition in your applications.

   5. When you click the Remove from role button, the current authenticated user is removed from the role TestRole.

      Note   This step demonstrates how to create and remove roles programmatically and how to determine whether a user is in a role programmatically. You can add and remove users from roles by using the AzMan MMC plug-in or the ASP.NET Configuration Tool. You can also configure access restrictions to pages and folders by using roles.

      For more information about using ASP.NET Role Management, see How To: Use Role Manager in ASP.NET 2.0. For more information about using AzMan, see How To: Use Authorization Manager (AzMan) with ASP.NET 2.0.

Deployment Considerations

In addition to the preceding guidance, consider the following deployment considerations:

• Deploy ADAM Instance on a Remote Server
• Use an existing ADAM Instance for your ASP.NET 2.0 Roles

Deploy ADAM Instance on a Remote Server

When using role manager, you should consider deploying your ADAM role store on a remote server. In order to deploy your ADAM instance on a remote server you must grant the necessary permissions to allow the account running your ASP.NET application to access the ADAM instance.

If your ASP.NET application runs under the default Network Service account, you must authorize the Web server machine account. If you have configured a custom application pool in IIS 6.0 running under a custom domain account, you must authorize that domain account.

The following instructions assume the ASP.NET application runs under the default Network Service account:

Authorize your Web server machine account to access the remote ADAM instance

You have to grant the permissions to the users to access that Adam partition. Use the ADAM ADSI to edit your partition.

1. On the server running the ADAM instance, create a local ADAM Readers group called ADAMReaders using Local Users and Groups in the Computer Management tools and add your web server machine account Domain/WebServernameto this group.
2. Open the ADAM ADSI Edit tool from the ADAM group in the Programs menu. Connect to your ADAM instance; in the Connection Settings dialog, select Well-known naming context, and select Configuration in the drop-down box. Click OK.
3. Select CN=Roles in the left-hand pane, right-click on CN=Readers in the right hand pane and then select Properties.
4. In the CN=Readers Properties dialog box**,** select the member attribute in the attributes list, and then click Edit.
5. Click Add Windows Account and add your Local ADAM Readers Group AdamServerName\ADAMReaders.

Use an Existing ADAM Instance for Your ASP.NET 2.0 Roles

In production, you may want to use an existing ADAM instance to store your ASP.NET 2.0 Roles. If you want to use an existing ADAM instance, you must:

• Import the AzMan schema into ADAM
• Perform the same steps described above for a new ADAM instance starting from Step 2–Configure the AzMan Policy Store in ADAM.

To import the AzMan schema into ADAM

1. On the computer where the ADAM instance is installed, click on the Start menu, click All Programs, click ADAM, and then click Adam Tools Command Prompt.

2. At the command prompt, run the following command to import the AzMan schema into the existing ADAM store. This command runs the LDIFDE executable, which creates, modifies, or deletes a directory object.

   ldifde -i -f MS-AzMan.ldf -s servername**:** portnumber -j . -c "CN=Schema,CN=Configuration,DC=X" "#schemaNamingContext"
   -b usernamedomain *

   When you type the command, replace servername and portnumber with your actual computer name and port number. The port number is the one you selected when you installed this instance of ADAM. By default, port 389 is used for the first ADAM instance but this may be changed at install time. Replace username and domain with the account name and domain name of an account that is authorized to administare this ADAM instance.

   You will be prompted for the password to the account you have specified. After you type the password, you will see the following output:

   Connecting to "servername: portnumber"
   Logging in as "username" in domain "domain" using SSPI
   Importing directory from file "MS-AzMan.ldf"
   Loading entries........................................
   39 entries modified successfully.
   
   The command has completed successfully
   
   

   Note   For information about the ldifde switches, type ldifde -? at the command prompt.

To configure the AzMan policy store

Proceed as described above for a new ADAM instance starting from Step 2–Configure the AzMan Policy Store in ADAM.

Additional Considerations

If you use Windows XP or Windows 2000, you must install the primary interop assembly for the AzMan COM object into the global assembly cache (GAC) before you can use the AuthorizationStoreRoleProvider. This assembly is already installed in the GAC on Windows Server 2003–based computers.

To install the primary interop assembly on Windows 2000

1. Run the installer for the Windows 2000 Authorization Manager Runtime (download from https://www.microsoft.com/downloads/details.aspx?FamilyID=7edde11f-bcea-4773-a292-84525f23baf7\&DisplayLang=en) The installer creates two subdirectories: one contains the setup file for the Authorization Manager and the other, called \pia, contains the primary interop assembly.
2. From the Windows Control Panel, run the Microsoft .NET Framework Configuration tool, and then open the Manage Assembly Cache option.
3. Use the Add an Assembly to the Assembly Cache option to navigate to the Authorization Manager Runtime Installation Directory**\pia** folder, and then add the Microsoft.Interop.Security.AzRoles.dll assembly to the cache.

Note   The \pia folder contains two versions of the primary interop assembly. The primary interop assembly for AzMan version 1.0 is in the \pia folder, and the primary interop assembly of AzMan version 1.2 in the \pia\1.2 folder. The V1.2 AzMan COM object exposes additional interfaces that will be of interest to advanced AzMan users, but does not offer additional functionality to users of the ASP.NET Roles Management API.

To install the primary interop assembly on Windows XP

1. Install the Windows Server 2003 Administration Tools Pack, available for download at https://www.microsoft.com/downloads/en/default.aspx. This download does not include the AzMan primary interop assembly.
2. To install the primary interop assembly, download the Windows 2000 Authorization Manager Runtime from https://www.microsoft.com/downloads/details.aspx?FamilyID=7edde11f-bcea-4773-a292-84525f23baf7&DisplayLang=en. Run the downloaded file, which unzips files (including the AzMan primary interop assembly) into a directory in the \pia folder.
3. From the Windows Control Panel, run the Microsoft .NET Framework Configuration tool, and then open the Manage Assembly Cache option.
4. Use the Add an Assembly to the Assembly Cache option to navigate to the Authorization Manager Runtime Installation Directory**\pia** folder, and then add the Microsoft.Interop.Security.AzRoles.dll assembly to the cache.

Additional Resources

• How To: Use Authorization Manager (AzMan) with ASP.NET 2.0
• An Introduction to ADAM

Feedback

Provide feedback by using either a Wiki or e-mail:

• Wiki. Security Guidance Feedback page: https://channel9.msdn.com/wiki/securityguidancefeedback/
• E-mail. Send e-mail to secguide@microsoft.com.

We are particularly interested in feedback regarding the following:

• Technical issues specific to recommendations
• Usefulness and usability issues

Technical Support

Technical support for the Microsoft products and technologies referenced in this guidance is provided by Microsoft Support Services. For product support information, please visit the Microsoft Product Support Web site at https://support.microsoft.com.

Community and Newsgroups

Community support is provided in the forums and newsgroups:

• MSDN Newsgroups:https://www.microsoft.com/communities/newsgroups/default.mspx
• ASP.NET Forums:http://forums.asp.net

To get the most benefit, find the newsgroup that corresponds to your technology or problem. For example, if you have a problem with ASP.NET security features, you would use the ASP.NET Security forum.

Contributors and Reviewers

• External Contributors and Reviewers: Jason Taylor, Security Innovation; Rudolph Araujo, Foundstone Professional Services
• Microsoft Consulting Services and PSS Contributors and Reviewers: Adam Semel, David Crawford, Tom Christian, Wade Mascia
• Microsoft Product Group Contributors and Reviewers: Stefan Schackow, Sudheer Mamidipaka
• Test team: Larry Brader, Microsoft Corporation; Nadupalli Venkata Surya Sateesh, Sivanthapatham Shanmugasundaram, Infosys Technologies Ltd.
• Edit team: Nelly Delgado, Microsoft Corporation; Tina Burden McGrayne, TinaTech Inc.
• Release Management: Sanjeev Garg, Microsoft Corporation