How To: Use Authorization Manager (AzMan) with ASP.NET 2.0

[AzMan is available for use in the following versions of Windows: Windows Server 2012, Windows 8, Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003, or Windows XP. It may be altered or unavailable in subsequent versions.]

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
• Authorization Manager (AzMan)
• Microsoft Windows Server 2003 operating system
• Microsoft Windows 2000 Server operating system
• Microsoft Windows XP Professional operating system

Summary

This How To shows you how to use the Authorization Manager (AzMan) in conjunction with the ASP.NET role manager API to manage roles, check user role membership, and authorize roles to perform specific operations against an AzMan policy store. The How To also explains how to use Authorization Manager's authorization model of tasks and operations through the AzMan COM API.

The benefit of using AzMan is that it enables you to define operations, group them into tasks, and then authorize roles to perform specific tasks. It also provides an administrative console for managing roles, tasks, operations, and users.

Contents

Objectives
Overview
Summary of Steps
Step 1. Install AzMan
Step 2. Create an AzMan Policy Store
Step 3. Define Tasks and Operations
Step 4. Create Roles and Assign Users in AzMan
Step 5. Configure Your ASP.NET Application to Use AuthorizationStoreRoleProvider
Step 6. Use Role Manager to Perform a Role Check
Step 7. Use AzMan APIs to Authorize Operations
ASP.NET Web Site Configuration Tool
Security Considerations
ADAM Considerations
Additional Resources

Objectives

• Identify when to use Authorization Manager (AzMan).
• Create a policy store, define tasks, operations, and role assignments using AzMan.
• Configure your Web application to use AuthorizationStoreRoleProvider.
• Use AzMan APIs to authorize operations.

Overview

Authorization Manager (AzMan) enables you to define individual operations, which can be grouped together to form tasks. You can then authorize roles to perform specific tasks and/or individual operations. AzMan provides an administration tool as a Microsoft Management Console (MMC) snap-in to manage roles, tasks, operations, and users. You can configure an AzMan policy store in an XML file, Active Directory, or in an Active Directory Application Mode (ADAM) store.

ASP.NET version 2.0 role management provides an API that enables you to manage application roles and users' membership of roles. By configuring the ASP.NET role manager to use the AuthorizationStoreRoleProvider, you can use the role management API against an AzMan policy store.

The AuthorizationStoreRoleProvider does not support AzMan business rules ("BizRules"), which are scripted extensions to authorization checks, because the current role manager implementation does not have the concept of extended data that can be passed along during an authorization check. To use AzMan BizRules, you need to use COM interop.

Roles API vs. Authorization Manager

ASP.NET role manager provides an API that enables you to manage application roles, add and remove users from roles, and check role membership, but it does not allow you to query whether a user is authorized to perform a named task or operation. AzMan allows you to define individual operations and combine them into tasks. With AZMan, in addition to role checks, you can also check whether a user can perform a task. Role assignment and task authorization can be configured outside of the application or performed programmatically within the application. The AzMan administration MMC snap-in allows administrators to change the tasks a role may perform at run time and to manage each user's membership of roles.

At run time, if you are using the ASP.NET roles API, you programmatically query a user's role membership. Using the AzMan COM API and the AccessCheck function, you query whether a user is authorized to perform a named task.

You should use AzMan to design and implement role-based authorization if you want to design a more fine-grained role-based authorization approach around operations and tasks, and if you want the additional flexibility of allowing an administrator to create, delete, and administer the permissions assigned to a role at run time.

Summary of Steps

To use the ASP.NET role manager to check user role membership in an Authorization Manager policy store, perform the following steps:

• Step 1. Install AzMan.
• Step 2. Create an AzMan policy store.
• Step 3. Define tasks and operations.
• Step 4. Create roles and assign users in AzMan.
• Step 5. Configure your ASP.NET application to use AuthorizationStoreRoleProvider.
• Step 6. Use role manager to perform a role check.
• Step 7. Use AzMan APIs to authorize operations.

Step 1. Install AzMan

AzMan is supported on Windows Server 2003, Windows XP Professional, and on Windows 2000 Server.

To install AzMan on Windows Server 2003

AzMan is part of Windows 2003, SP1 or later, so you can obtain AzMan by installing this version of the operating system. You can download it from https://windowsupdate.microsoft.com.

To install AzMan on Windows XP Professional

Install the Windows Server 2003 Administration Tools Pack, which you can download from https://www.microsoft.com/downloads/details.aspx?FamilyID=e487f885-f0c7-436a-a392-25793a25bad7&DisplayLang=en. This tools pack enables remote server management of Windows Server 2003, but it also includes AzMan.

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

To install AzMan on Windows 2000

Install the Windows 2000 Authorization Manager Runtime, which you can download from https://www.microsoft.com/downloads/details.aspx?FamilyID=7edde11f-bcea-4773-a292-84525f23baf7&DisplayLang=en. You must be running Windows 2000 Server Service Pack 4 or later. You must also install MSXML 4.0 or later.

Note that this installs the runtime components only; it does not install the AzMan administration MMC snap-in. You can still use the MMC snap-in on a Windows Server 2003 system, or on a Windows XP system that has the Windows Server 2003 Administration Tools Pack installed, to remotely administer AzMan on a Windows 2000 Server.

On Windows XP and Windows 2000, you must install the primary interop assembly for the AzMan COM object into the global assembly cache before you can use the ASP.NET AuthorizationStoreRoleProvider to work with an AzMan store. This assembly is already installed in the global assembly cache on Windows Server 2003 systems.

To install the primary interop assembly on Windows 2000

When you run the installer for the Windows 2000 Authorization Manager Runtime, it creates two subdirectories. One contains the setup file for the Authorization Manager and the second subdirectory, called \pia, contains the primary Interop assembly.

1. From the Windows Control Panel, run the Microsoft .NET Framework Configuration tool. Open the Manage Assembly Cache option.
2. Using the Add an Assembly to the Assembly Cache option, navigate to the Authorization Manager Runtime Installation Directory**\pia** folder and 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 version 1.0 of AzMan is in the \pia folder, and the primary interop assembly of version 1.2 of AzMan is in the \pia\1.2 folder. The version 1.2 AzMan COM object exposes additional interfaces that will be of interest to advanced users of AzMan, but it does not offer additional functionality to users of the ASP.NET Roles Management API.

To install the primary interop assembly on Windows XP Professional

1. To install AzMan on a computer running Windows XP, install the Windows Server 2003 Administration Tools Pack, as explained earlier. However, this download does not include the AzMan primary interop assembly.
2. To install the primary interop assembly, download the Windows 2000 Authorization Manager Runtime and run the installer to extract the component files, which includes the primary interop assembly. Follow the earlier instructions for Windows 2000.

Step 2. Create an AzMan Policy Store

You can create AzMan policy stores in an XML file, Active Directory, or ADAM. In this step, you create an AzMan policy store in an XML file.

To create an AzMan Policy store

1. At the Windows command prompt, enter azman.msc to open the Authorization Manager MMC snap-in.
2. On the Action menu, click Options, and then click Developer mode. Developer mode exposes options, such as store creation, that are not available in Administrator mode.
3. On the Action menu, click New Authorization Store. Set the Authorization store type as XML File.
4. Enter the full store name, for example: C:\RolesData\AzManStore.xml. You can click the Locations button to navigate to the AzMan store, or you can create a folder where you will store it.
5. Right-click AzManStore.xml, and then click Properties. In the Properties window, click the Security tab.
6. Under Authorization Manager user role, 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 the original caller or a fixed identity, or if it runs under a different 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 AzManStore.xml is selected in the console tree. On the Actions menu, click New Application.
2. Enter a name for your application. For this example, enter AzManDemo in the Application Name box, and leave the Description and Version Info boxes empty.

Step 3. Define Tasks and Operations

Use the following steps to define tasks and operations. Note that you do not need to perform this step if you intend to use only the ASP.NET Role Manager API, which can only authorize users on role membership; it cannot authorize users by application task or operation. Perform these steps if you want to use the AzMan COM API to authorize by task or operation.

To define tasks

1. On the console tree, expand AzManDemo, and then expand Definitions.
2. Right-click Task Definitions, and then click New Task Definition.
3. In the Name box, type Privileged Task, and then click OK.

To define operations

1. On the console tree, expand AzManDemo, and then expand Definitions.
2. Right-click the Operation Definitions, and then click New Operation Definition.
3. In the Name box, type Do Sensitive Operation, type 1 in the Operation number box, and then click OK.

To associate operations with tasks

1. In the Task Definitions folder, double-click the Privileged Task, task that you previously created.

2. Click the Definition tab, and then click Add.

3. In the Add Definition dialog box, click the Operations tab, and then select the Do Sensitive Operation check box. Click OK, and then click OK again. This assigns the newly created operations to the task named Privileged Task.

   Note   An AzMan task is an optional abstraction and if an application has only a few operations defined, it may make sense to just use operations.

For more information about using Authorization Manager, see Using Authorization Manager on Microsoft TechNet.

Step 4. Create Roles and Assign Users in AzMan

In this step, you use the AzMan administration MMC snap-in to create a role named Manager. You then assign the task that you created in the previous step to the role.

To define roles with the AzMan administration MMC snap-in

1. At the Windows command prompt, type azman.msc to open the Authorization Manager MMC snap-in.
2. On the Action menu, click Options, and then click Administrator mode. Administrator mode exposes fewer options than developer mode, but it exposes only those configuration options that can be changed at run time, such as assigning tasks to roles and assigning users to roles.
3. On the AzMan Management Console tree, expand AzManDemo, and then expand Definitions.
4. Right-click Role Definitions, and then click New Role Definition.
5. In the Name box, type Manager, and then click OK.

To assign a user to a role with the Administration UI

1. Right-click the Role Assignments folder, and then click Assign Roles.
2. In the dialog box that appears, click the Manager check box, and then click OK.
3. Right-click the Manager role listed after the Role Assignments folder in the console tree, and then click Assign Windows Users and Groups.
4. Type the name of the Windows user account you are logged on as, click Check Names, and then click OK. This assigns your user account to the Manager role.

To associate tasks with roles

1. In the Role Definitions folder, double-click the Manager role you created previously.
2. Click the Definition tab, and then click Add.
3. In the Add Definition dialog box, click the Tasks tab, and then click the Privileged Task check box (this is the task you created in the previous step). Click OK twice. This assigns the Privileged Task task to the Manager role.

Step 5. Configure Your ASP.NET Application to Use AuthorizationStoreRoleProvider

In this step, you configure role management in an ASP.NET application to use the AzMan store.

To connect to the AzMan store

1. Create a new ASP.NET Web site named AzManRoles.

2. Define a connection string to the AzMan policy store in the <connectionStrings> element of the Web.config file. For example, to create a connection string to C:\RolesData\AzManStore.xml, use the following configuration.

   <configuration> 
     <connectionStrings> 
       <add name="LocalPolicyStore" 
            connectionString="msxml://c:/RolesData/azmanstore.xml" />
     </connectionStrings> 
   </configuration> 
   
   

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

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

In the preceding configuration file fragment, you define a <providers> element that uses the AuthorizationStoreRoleProvider, with the connectionStringName attribute set to the name of the connection string you defined in the previous step, and you must set the applicationName attribute to the name of the AzMan application you created in the AzMan store.

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 6. Use Role Manager to Perform a Role Check

At run time, you can use roles to authorize access in two ways:

• Use role authorization to restrict access to pages and folders.
• Use the roles API to programmatically check for role membership.

Role Authorization

A typical use for roles is to establish rules that allow or deny access to pages or folders. You can set up such access rules in the <authorization> section of the Web.config file. The following example allows users in the role of members to view pages in the folder named memberPages and denies access to anyone else.

<configuration>
   <location path="memberPages">
       <system.web>
            <authorization>
               <allow roles="Manager" />
               <deny users="*" />
            </authorization>
          </system.web>
        </location>
   <!-- other configuration settings here -->
</configuration>
  

Roles API

If you are using Windows authentication in your application, or if you are using Forms authentication with the ASP.NET membership feature, you can use Roles API methods such as Roles.IsUserInRole("roleName") to test for role membership for the currently authenticated user or **Roles.GetRolesForUser()**to return a string array of all roles for the user.

You can use Roles.IsUserInRole("username", "roleName") to test for role membership for a named user.

For more details, see How To: Use Role Manager in ASP.NET 2.0.

Step 7. Use AzMan APIs to Authorize Operations

With AzMan, the primary mechanism to determine access to a given operation is the AccessCheck API. In this step, you use the Authorization Manager API in an ASP.NET application to query the operations that are in a task to determine whether the current user is authorized to perform them. The ability in the AzMan API to query for authorization to perform an operation or task exceeds the capabilities of the ASP.NET Role Management API, which only supports role membership checks.

To connect to the AzMan store

1. Create a new C# ASP.NET Web site named AccessingTasks.

2. Add a reference to the AzMan COM library. In the Add Reference dialog box, click the COM tab, and then select azroles 1.0 Type Library. Click OK.

3. Add the following using statements to the code page of the Default.aspx page.

   using AZROLESLib;
   using System.Collections.Specialized;
   using System.Security.Principal;
   
   
   

4. To open the AzMan policy store, add the following code. Use the same connection string as defined at the beginning of step 5.

   AzAuthorizationStoreClass AzManStore = new AzAuthorizationStoreClass();
   AzManStore.Initialize(0, ConfigurationManager.ConnectionStrings
               ["LocalPolicyStore"].ConnectionString, null);
   IAzApplication azApp = AzManStore.OpenApplication("AzManDemo", null);
   
   

Now check whether a user is authorized to complete the operation. The sample code in the following procedure checks if the authenticated user is authorized to perform an operation.

To check whether a user is authorized to perform an operation

1. Construct a representation of the client's security context. The context is similar to a token in that it caches role mappings for a user. To create the client's context object:

   1. If your application uses Windows authentication (the application Web.config file specifies authentication mode='Windows', and Microsoft Internet Information Services (IIS) has been configured to require integrated Windows authentication), construct the client context a follows.

          // Get the current user context 
          IPrincipal userPrincipal = HttpContext.Current.User;
          WindowsIdentity userIdentity = userPrincipal.Identity as WindowsIdentity;
      
          IAzClientContext clientContext =
              azApp.InitializeClientContextFromToken(
                     (ulong)userIdentity.Token, null);
      
      

   2. If your application uses an authentication mechanism where you only have the original caller's user name available, but you do not have the password, you can construct the client context as shown in the following example.

      IAzClientContext clientContext =
         azApp.InitializeClientContextFromName(name, domain, null);
      
      

2. Use the client context object and AzMan to determine whether the user is authorized to perform the operations.

   The AccessCheck method returns an object array that is actually an array of integers, one for each requested operation. If any of the integers are nonzero, the user is not authorized to perform the corresponding operation in the operations array.

       // Create an object array describing the operation IDs to query
   
       // In this simple example, query for the single operation called
       // 'Do Sensitive Operation' which has an ID of 1.
       object[] operationIds = new object[] {1};
       // Check if user has access to the operations
       // The first argument, "Auditstring", is a string that is used if you 
       // have run-time auditing turned on
       object[] result = (object[])clientContext.AccessCheck("Auditstring",
                     new object[1], operationIds, null, null, null, null, null);
   
       // Test the integer array we got back to see which operations are
       // authorized
       int accessAllowed = (int)result[0];
       if (accessAllowed != 0)
       {
            // current user not authorized to perform operation
           Response.Write("User not authorized for operation: " +
                "Do Sensitive Operation" + "<br />");
       }
       else
       {
           // current user authorized to perform operation
           Response.Write("User authorized for operation " +
                "Do Sensitive Operation" + "<br />");
       }
   
   
   

When you save and run this code, the resulting page reports whether the current user is authorized to perform the operation.

ASP.NET Web Site Configuration Tool

The ASP.NET Web Site Configuration tool is built into Visual Studio 2005. You can use this tool to assign users to roles, but only if your application uses forms authentication, because user management is disabled in this tool if you are using Windows authentication.

To assign users to roles with the ASP.NET Web Site Configuration tool

1. On the Website menu, click ASP.NET Configuration.
2. Click the Security tab.
3. Click Create or Manage Roles
4. In the table of roles, click Manage next to the role that you want to add a user to.
5. Locate the desired user, and then click Add Role.

Security Considerations

If an XML policy store is used, access rights are controlled by NTFS ACLs. Reading a policy store requires Read access. Writing a policy store requires both Read and Write access. Any account that had rights to the XML file has rights to all applications and all scopes within the file. There is no support for delegated rights with the XML policy store.

If an Active Directory or ADAM policy store is used, rights are expressed by way of roles defined in the store. Domain accounts (either a domain user or a machine account) can be added to the Reader and Administrator roles on the policy store, application, or scope using the AzMan MMC. Delegated rights are supported for Active Directory policy stores.

ADAM Considerations

This How To describes how to configure an AzMan policy store in an XML file. You can also create AzMan stores in Active Directory or in ADAM. For more information about using AzMan with a store in ADAM, see How To: Use ADAM for Roles in ASP.NET 2.0.

Additional Resources

• How To: Use Role Manager in ASP.NET 2.0
• How To: Use ADAM for Roles in ASP.NET 2.0
• Role-Based Access Control for Multi-tier Applications Using Authorization Manager on Microsoft TechNet
• Madam, I'm ADAM, an introduction to ADAM, on MSDN
• Authorize It: Use Role-Based Security in Your Middle Tier .NET Apps with Authorization Manager in MSDN Magazine

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, see 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://msdn.microsoft.com/newsgroups/default.asp
• 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: Andy Eunson, 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 IT Contributors and Reviewers: Devendra Tiwari, Shawn Veney
• Microsoft Product Group Contributors and Reviewers: Dave McPherson, Stefan Schackow, Sudheer Mamidipaka
• MSDN Contributors and Reviewers: Kent Sharkey, Microsoft Corporation
• 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