Return to
HomePage
Note:
This document is now live on MSDN! See http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnpag2/html/PAGHT000018.asp
How To: Use ADAM for Roles in ASP.NET 2.0
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 about using
AzMan in your ASP.NET 2.0 applications, see "How To: Use Authorization Manager
(AZMan) with ASP.NET 2.0," available at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnpag2/html/PAGHT000019.asp.
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:
http://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 http://windowsupdate.microsoft.com.
*
Windows XP Professional: Install the Windows Server 2003 Administration Tools Pack, which is available for download at http://www.microsoft.com/downloads. 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
http://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
http://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:
* On the
Start menu, click
Control Panel.
* Open
Administrative Tools, and then double-click the
Local Security Policy option.
* Under
Security Settings, expand
Local Policies, then select
Security Options.
* In the
Policy list, double-click
Network Access: Sharing and Security model for local accounts.
* 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, partitionIn 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:
* Create a new empty ASP.NET Web site, and name it
AdamRoles.
* Add a Web.config file to your project.
* 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="false"
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>
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 runat="server">
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 runat="server">
<title>Untitled Page</title>
</head>
<body>
<form id="form1" runat="server">
<div>
<asp:Button ID="Button1" runat="server" Text="Add to role"
OnClick="Button1_Click" /><br />
<br />
<asp:Button ID="Button2" runat="server" Text="Remove from role"
OnClick="Button2_Click" /><br />
<br />
<asp:Label ID="Label1" runat="server"
Text="Label">
</asp:Label>
</div>
</form>
</body>
</html>
2. Run the application. Note the following features about this application:
* When you start it up, the code in the *Page_Load* event handler creates the role *TestRole*, if it does not already exist.
* The text of
Label1 shows whether or not the current authenticated user is a member of the
TestRole role.
* 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.
* 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.
* 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," available at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnpag2/html/PAGHT000013.asp. For more information about using
AzMan, see "How To: Use Authorization Manager
(AzMan) with ASP.NET 2.0," available at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnpag2/html/PAGHT000019.asp.
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 instanceYou 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/WebServername to 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 username domain *
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 storeProceed 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
http://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 http://www.microsoft.com/downloads. 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
http://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," available at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnpag2/html/PAGHT000019.asp
* "An Introduction to ADAM" at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnclinic/html/scripting01132004.asp
Return to
HomePage
Channel 10: Black Friday Deals on Windows 7 Machines
ASP.NET: Presenting in Europe Next Week
WindowsClient: You know your post rate has gone down...
Silverlight: Geek Profiles – Scott Guthrie
