Documente Academic
Documente Profesional
Documente Cultură
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 Microsoft Windows Server 2003 operating system or Microsoft Windows XP Professional Service Pack 1 or later operating system
Summary
This How To shows you how to use the ASP.NET 2.0 role manager. The role manager eases the task of managing roles and performing role-based authorization in your application. It shows how to configure the various role providers for use with your Web application, how to create new roles, how to add a user to a role, and how to use the role management API for roles-based authorization.
Contents
Objectives Overview Summary of Steps Step 1. Configure Your Role Store Step 2. Configure Your Role Provider in Web.config Step 3. Create and Assign Roles Step 4. Perform Role-Based Authorization Additional Considerations Additional Resources
Objectives
Configure an ASP.NET Web application to use role management.
msdn.microsoft.com//ff647401.aspx 1/14
12/02/2011
How To: Use Role Manager in ASP.NE Learn how to configure the SqlRoleProvider, WindowsTokenRoleProvider, and AuthorizationStoreRoleProvider. Create and assign roles by using ASP.NET configuration tools, SQL scripts, and the role management APIs. Perform role based authorization in an ASP.NET Web application.
Overview
ASP.NET version 2.0 provides a new role manager feature that includes a roles management API that allows you to create and delete roles and assign and remove users from roles. The role manager stores its data in an underlying data store that it accesses through an appropriate role provider for that data store. The main benefits of using role manager are that it allows you to look up users' roles without writing and maintaining code. Additionally, the role providers offer a consistent way for you to check the role membership of your users, regardless of the underlying data store. Therefore, if your role store were to change tomorrow, you would only need to change the configuration settings to make your code work. Supplied role providers include: SqlRoleProvider. This is used where the role store is kept in SQL Server. WindowsTokenRoleProvider. This is a read-only provider that retrieves role information for a Windows user account based on the account's Windows security group membership. You cannot create, add to, or delete roles with this provider. AuthorizationStoreRoleProvider. This is used if your application uses Authorization Manager (AzMan). It uses an AzMan policy store in an XML file, in Active Directory, or in Active Directory Application Mode (ADAM) as its role store. It is typically used in an intranet or extranet scenario where Windows authentication and Active Directory is used for authentication. To perform role management, your ASP.NET application must be able to identify and authenticate its users in some way. For example, it might use Windows authentication or Forms authentication. This How To shows you how to set up and configure a role store and a role provider and use rolebased authorization in your ASP.NET applications. Additionally, it demonstrates some of the basic roles API calls available to work with roles programmatically.
Summary of Steps
To use the role manager in your application, perform the following steps: Step 1. Step 2. Step 3. Step 4. Configure your role store. Configure your role provider in Web.config. Create and assign roles. Perform role-based authorization.
Using SqlRoleProvider
If you want to store roles in SQL Server, you use the SqlRoleProvider. By default, roles are stored in a database named Aspnetdb in a SQL Express database instance in the \app_data folder
msdn.microsoft.com//ff647401.aspx 2/14
12/02/2011
How To: Use Role Manager in ASP.NE beneath your application's virtual directory root folder. You can also configure the SqlRoleProvider to use a local or remote instance of SQL Server.
To use a SQL Express database role store in the Website \app_data folder You do not have to create or configure this database. The first time you perform an operation that uses the role management API, ASP.NET automatically creates a database named Aspnetdb, configures it, and sets appropriate permissions on it. ASP.NET configures the SQL Express database with a database login for the default accounts used to run ASP.NET applications (Network Service on Windows Server 2003 and ASPNET on Windows 2000) and grants them full access to the Aspnetdb database. If you have configured ASP.NET to run using a custom service account, you must create a SQL login for that account, and add the login to the aspnet_Roles_FullAccess role in the Aspnetdb database. For more information about running ASP.NET with a custom identity, see How To: Create a Service Account for an ASP.NET 2.0 Application. To install the role management database in SQL Server 1. Log on to Windows using an account that has administration rights for your SQL Server instance. 2. Open a command prompt window and execute the following command to install the role management database. Aspnet_regsql.exeES sqlinstanceA r Note that this program is located in the %windir%\Microsoft.NET\Framework\ {version} folder. When you type the command, replace version with the version of the .NET Framework that you are using and sqlinstance with the name of the SQL Server instance you want to install the role management database in. You will see the following output:
Start adding the following features: Rolemanager ............ Finished.
Note For information about the switches for Aspnet_regsql.exe, type Aspnet_regsql.exe -? at the command prompt. To grant permissions in the database You need to create a database login for your Web application's process account; by default, this is the Network Service account. If you have configured a custom account to run ASP.NET, you must grant permissions to that account. Note If you have configured your ASP.NET application to use impersonation, your ASP.NET application executes using the security context of the original caller. To access data in a SQL Server database, you must usually create a database login for the original caller and grant access to the required data. However, the role management system accesses the Aspnetdb database by using the process identity regardless of whether your application uses impersonation.
msdn.microsoft.com//ff647401.aspx 3/14
12/02/2011
How To: Use Role Manager in ASP.NE 1. Open SQL Server Enterprise Manager, expand Security, and then expand Logins for the server hosting the role management database. Create a new login for your Web application's process account (for example, NT AUTHORITY/Network Service). 2. Set the default database to Aspnetdb. 3. Under the Databases node in Enterprise Manager, expand the Aspnetdb database entry, and then click Roles. Right-click aspnet_Roles_FullAccess, and then click Properties. In the Database Role Properties dialog box, click Add, and then select the database login you created in the previous step to add the login to that role.
Note Aspnet_regsql.exe creates three database roles with differing levels of access to the role management database: FullAccess gives rights to create and delete roles, and add and remove users from those roles. BasicAccess allows role membership checks for the current user only. ReportingAccess allows a page to check which roles exist and which users belong to them.
Using WindowsTokenRoleProvider
You use the WindowsTokenRoleProvider with ASP.NET applications that use Windows authentication. It is a read-only provider that retrieves role information for a Windows user based on Windows security groups. You cannot create, add to, or delete roles with this provider. Instead, you must use the Windows Computer Management or Active Directory Users and Computers administration tools. The Windows security system acts as role store for this provider, so no additional configuration is required to set up the role store.
Using AuthorizationStoreRoleProvider
Use the AuthorizationStoreRoleProvider to store roles data in an AzMan policy store in an XML file, in Active Directory, or ADAM. AzMan is supported on Windows Server 2003, Windows 2000 Server, and on Windows XP Professional. For more information about how to install AzMan and configure an AzMan policy store, see the following resources: If you want to create the store as a XML file, see How To: Use Authorization Manager (AzMan) with ASP.NET 2.0. If you want to create the store using ADAM, see How To: Use ADAM for Roles in ASP.NET 2.0.
Using SqlRoleProvider
To use the role store in the default SQL Express instance in a database in your Web site's \app_dir folder, add the following configuration to your application's Web.config file.
<system.web> <roleManager enabled="true" /> </system.web>
This configuration enables role management and causes your application to use the default
msdn.microsoft.com//ff647401.aspx 4/14
12/02/2011
How To: Use Role Manager in ASP.NE provider named AspNetSqlRoleProvider defined in the Machine.config file. This uses the local SQL Express instance.
To use a role store in SQL Server, add a connection string to point to your role database and add a role provider definition in the Web.config file, as shown here.
<configuration> <connectionStrings> <add name="SqlRoleManagerConnection" connectionString="Data Source=sqlinstance; Initial Catalog=aspnetdb;Integrated Security=SSPI;"> </add> </connectionStrings> </configuration> <roleManager enabled="true" defaultProvider="SqlRoleManager"> <providers> <add name="SqlRoleManager" type="System.Web.Security.SqlRoleProvider" connectionStringName="SqlRoleManagerConnection" applicationName="MyApplication" /> </providers> </roleManager>
Using WindowsTokenRoleProvider
The Windows security system acts as role store for this provider, and Windows groups represent roles. You can use this provider when you use Windows authentication. To do this, add the following configuration to your application's Web.config file.
<authentication mode="Windows" /> <roleManager enabled="true" defaultProvider="AspNetWindowsTokenRoleProvider" />
This configuration enables role management and uses the role provider named AspNetWindowsTokenRoleProvider, which is defined in the Machine.config file.
Using AuthorizationStoreRoleProvider
The AuthorizationStoreRoleProvider is used to store roles data in an AzMan policy store in an XML file, in Active Directory, or in ADAM. To configure this provider, add a connection string to point to the relevant policy store and then add a role provider definition in the Web.config file. The following connection string refers to an XML-based policy store contained in a file named Azmanstore.xml.
<configuration> <connectionStrings> <add name="AzManPolicyStoreConnectionString" connectionString="msxml://c:/RolesData/azmanstore.xml" /> </connectionStrings> </configuration>
msdn.microsoft.com//ff647401.aspx
5/14
12/02/2011
</connectionStrings> </configuration>
The following configuration shows how to enable role management and use the provider named RoleManagerAzManADAMProvider. This uses the connection string shown earlier to connect to an ADAM policy store.
<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, C ulture=neutral, publicKeyToken=b03f5f7f11d50a3a" connectionStringName="AzManPolicyStoreConnectionString" applicationName="AzManDemo"/> </providers> </roleManager>
12/02/2011
How To: Use Role Manager in ASP.NE d. Click Create or Manage Roles. e. Use the form to add your application roles. 2. Assign users to roles as follows: a. In Visual Studio .NET, click ASP.NET Configuration on the Website menu. b. On the Home tab, click Security. c. Click Create or Manage Roles. d. In the Add/Remove Users column, click Manage for a role you have created. This opens a form where you can add or remove users from the role.
There are 19 role-managing stored procedures created inside the role management database. Most of these stored procedures have purposes analogous to calls in the role management API.
Note Role names are not case sensitive. If you attempt to create the same role twice, an exception is thrown. The following code shows how to add uses to roles.
// Example 1 - Add one user to one role Roles.AddUserToRole("TestOne", "ExampleRole1"); // Example 2 - Add one user to several roles Roles.AddUserToRoles("TestTwo",
msdn.microsoft.com//ff647401.aspx
7/14
12/02/2011
new string[] { "ExampleRole1", "ExampleRole2" }); // Example 3 - Add several users to one roles Roles.AddUsersToRole( new string[] { "TestTwo", "TestThree" }, "ExampleRole3"); // Example 4 - Add several users to several roles Roles.AddUsersToRoles( new string[] { "TestThree", "TestFour" }, new string[] { "ExampleRole4" });
Note Both the AddUser and RemoveUser methods throw a TargetInvocationException if you specify a role that does not exist or if you specify an invalid Windows user account name. The inner exception gives the reason for the failure. None of the methods mentioned earlier can be used against a WindowsTokenRoleProvider.
12/02/2011
How To: Use Role Manager in ASP.NE 1. Use Visual Studio.NET 2005 to create a Web site, add a Web.config file, and configure the role store and SqlRoleProvider or AuthorizationStoreRoleProvider as described in steps 1 and 2 of this How To. 2. Using the Internet Information Services MMC snap-in, edit the properties of the Web site. Edit the Anonymous access and authentication control on the Directory security tab. Clear the Anonymous access check box and select the Integrated Windows authentication check box. 3. In the Web.config file, enable Windows authentication.
<system.web> ... <authentication mode="Windows"/> ... </system.web>
msdn.microsoft.com//ff647401.aspx
9/14
12/02/2011
<br /> <asp:Button ID="Button2" runat="server" Text="Remove from role" OnClick="Button2_Click" /><br /> <br /> <asp:Label ID="Label1" runat="server" /> </div> </form> </body> </html>
5. Run the application. Note the following features about this application: a. When you browse to the application, the code in the Page_Load event handler creates the role TestRole if it does not already exist. The text of Label1 shows whether 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 role management 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. If you click the Remove from role button again before clicking the Add to role button, the call to Roles.RemoveUserFromRole throws an exception because the user is already not in the role TestUser and cannot be removed twice. You must code for this condition in your applications. To control access to pages and folders using roles 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>
12/02/2011
How To: Use Role Manager in ASP.NE Authentication check box. 3. In the Web.config file, enable Windows authentication.
<system.web> ... <authentication mode="Windows"/> ... </system.web>
5. Run the application. A list of roles that correspond to the Windows groups that the authenticated user is a member of is displayed. Note the following features about this application: a. Because WindowsTokenRoleProvider is read-only, you cannot create, assign to, or remove users from roles. The WindowsTokenRoleProvider supports only the IsUserInRole and GetRolesForUser methods of the role management API. The text of Label1 shows which Windows groups the currently logged on user is a member of. The WindowsPrincipal class supports an override of the IsInRole method that accepts a WindowsBuiltinRole enumeration. This method allows you to test against membership of common Windows groups. The WindowsBuiltInRole enumeration contains members representing common groups such as Administrators, Guest, PowerUser, and User as shown here.
WindowsPrincipal User = new WindowsPrincipal((WindowsIdentity)HttpContext.Current.User.Identity); if (User.IsInRole(WindowsBuiltInRole.PowerUser)) { ... }
msdn.microsoft.com//ff647401.aspx
11/14
12/02/2011
To control access to pages and folders using built-in roles with the WindowsTokenRoleProvider You can control access to pages or folders to members of one of the built-in Windows groups by specifying the role in the format BUILTIN\groupName. The following example allows users in the built-in administrators group to view pages in the folder named memberPages and denies access to anyone else.
<configuration> <location path="memberPages"> <system.web> <authorization> <allow roles="BUILTIN\Administrators" /> <deny users="*" /> </authorization> </system.web> </location> <!-- other configuration settings here --> </configuration>
Additional Considerations
If a user's browser accepts cookies, you can store role information for that user in a cookie on the user's computer. On each page request, ASP.NET reads the role information for that user from the cookie. This can improve application performance by reducing the amount of communication required with the roles data store. To configure and enable role caching, set cacheRolesInCookie = true as shown here.
<roleManager enabled="true" cacheRolesInCookie="true" cookieName=".ASPXROLES" cookieTimeout="30" cookiePath="/" cookieRequireSSL="false" cookieSlidingExpiration="true" cookieProtection="All" defaultProvider="AspNetSqlRoleProvider" createPersistentCookie="false" maxCachedResults="25"/>
If the role information for a user is too long to store in a cookie, ASP.NET stores only the most recently used role information in the cookie, and then it looks up additional role information in the data source as required. To secure the role cookie: Set cookieRequireSSL to true to ensure the cookie is only used over an SSL protected channel. Set createPersistentCookie to false to prevent the cookie from being stored on the client computer, in which case the cookie is only used to protect the current session. Set cookieTimeout to the number of minutes for which the cookie is valid.
Additional Resources
How To: Use Authorization Manager (AzMan) with ASP.NET 2.0
msdn.microsoft.com//ff647401.aspx 12/14
12/02/2011
How To: Use Role Manager in ASP.NE How To: Use ADAM for Roles in ASP.NET 2.0
Feedback
Provide feedback by using either a Wiki or e-mail: Wiki. Security Guidance Feedback page: http://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 http://support.microsoft.com.
Retired Content
This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid
msdn.microsoft.com//ff647401.aspx 13/14
12/02/2011
How To: Use Role Manager in ASP.NE when originally published, but now link to sites or pages that no longer exist.
msdn.microsoft.com//ff647401.aspx
14/14