The primary purpose of establishing roles is to give you an easy way to manage access rules for groups of users. You create users and then assign the users to roles (in Windows, to groups). A typical use is to then create a set of pages that you want to restrict to certain users. Often you isolate these restricted pages in a folder by themselves. Then you can establish rules that grant and deny access to restricted folders. For example, you can configure the site so that members or managers have access to the pages in the restricted folder and all other users are denied access. If an unauthorized user tries to view a restricted page, the user either sees an error or is redirected to a page that you specify.

To work with roles, you must be able to identify users in your application so that you can determine whether the user is in a specific role. You can configure your application to establish user identity in two ways: Windows authentication and forms authentication. If your application runs in a local area network (that is, in a domain-based intranet application), you can identify users by using their Windows domain account name. In that case, a user's roles are the Windows groups that the user belongs to.

In Internet applications or other scenarios where it is impractical to use Windows accounts, you can use forms authentication to establish user identity. For this task, you typically create a page where users can enter a user name and password and then you validate the user's credentials. The ASP.NET Login controls can perform much of this work for you, or you can create a login page and use the FormsAuthentication class to establish a user identity.

Note:
Roles do not work with users who have not established an identity in your application (anonymous users).

If you use Login controls or forms authentication to establish user identity, you can also use role management together with membership. In this scenario, you use membership to define users and passwords. You can then use role management to define roles and assign members to those roles. However, role management does not depend on membership. As long as you have a way in your application to set user identity, you can use role management for authorization.

You can access roles as a Windows Communication Framework (WCF) service by using the ASP.NET roles service. The roles service enables you to check a user's roles from any application that can read or consume a WCF service. For example, you could check a user's roles from a Windows Forms application, from a Web application, or from an application that does not use the .NET Framework. For more information about the Roles application service, see Windows Communication Foundation Role Service Overview.

Role management is not limited to restricting rights to pages or folders. Role management provides an API that you can use to determine programmatically whether a user is in a role. This enables you to write code to take advantage of roles and perform any application tasks based not only on who the user is but also on what roles the user is in.

If you establish user identity in your application, you can use the role-management API methods for creating roles, adding users to roles, and obtaining information about which users are in which roles. These methods enable you to create your own interface for managing roles.

If your application uses Windows authentication, the role management API offers fewer facilities for role management. For example, you cannot use role management to create new roles. Instead, you use Windows user and group management to create user accounts and groups and assign users to groups. Role management can then read Windows user and group information so that you can use the information for authentication.

If you are using the ASP.NET roles service, you can check whether a user belongs to a particular role or to retrieve all the roles for a user. However, you cannot manage roles through the roles service API.

To work with role management, you first enable it and optionally configure access rules that can take advantage of roles. You can then use role management functions at run time to work with the roles.

Role Management Configuration

To use ASP.NET role management, you enable it in an application's Web.config file by using a setting such as the following:

<roleManager enabled="true" cacheRolesInCookie="true" > </roleManager>

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 shows how to allow 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="members" /> <deny users="*" /> </authorization> </system.web> </location> <!-- other configuration settings here --> <configuration>

For more information about how to set up access rules, see ASP.NET Authorization.

You must also create roles such as manager or member and then assign user IDs to the roles. If your application uses Windows authentication, you use the Windows Computer Management tool to create users and groups.

If you are using forms authentication, you can set up users and roles with the ASP.NET Web Site Administration Tool. If you prefer, you can perform this task programmatically by calling various role-manager methods. The following example shows how to create the role members:

Visual Basic

Roles.CreateRole("members")

C#

Roles.CreateRole("members");

The following example shows how to add the user JoeWorden individually to the role manager, and how you can add the users JillShrader and ShaiBassli to the role members at one time:

Visual Basic

Roles.AddUsersToRole("JoeWorden", "manager") Dim userGroup(2) As String userGroup(0) = "JillShrader" userGroup(1) = "ShaiBassli" Roles.AddUsersToRole(userGroup, "members")

C#

Roles.AddUsersToRole("JoeWorden", "manager"); string[] userGroup = new string[2]; userGroup[0] = "JillShrader"; userGroup[1] = "ShaiBassli"; Roles.AddUsersToRole(userGroup, "members");

Note:
The role management features are not available through the ASP.NET roles service. The roles service can return information only about a particular user.

Working with Roles at Run Time

If User.IsInRole("members") Then
   buttonMembersArea.Visible = True
End If

if (User.IsInRole("members"))
{
   buttonMembersArea.Visible = True;
}

Dim userRoles() as String = CType(User, RolePrincipal).GetRoles()

string[] userRoles = ((RolePrincipal)User).GetRoles();

Caching Role Information

Concepts

Other Resources