Understanding Role Management

Role management helps you manage authorization, which enables you to specify the resources that users in your application are allowed to access. Role management lets you treat groups of users as a unit by assigning users to roles such as manager, sales, member, and so on. (In Windows, you create roles by assigning users to groups such as Administrators, Power Users, and so on.)

After you have established roles, you can create access rules in your application. For example, your site might include a set of pages that you want to display only to members. Similarly, you might want to show or hide a part of a page based on whether the current user is a manager. By using roles, you can establish these types of rules independent from individual application users. For example, you do not have to grant individual members of your site access to member-only pages. Instead, you can grant access to the role of member and then just add and remove users from that role as people sign up or let their memberships lapse. For more information, see Walkthrough: Managing Web Site Users with Roles.

Users can belong to more than one role. For example, if your site is a discussion forum, some users might be in the roles of both member and moderator. You might define each role to have different rights on the site, and a user who is in both roles would then have both sets of rights.

Even if your application has only a few users, you might still find it convenient to create roles. Roles give you flexibility to change permissions and add and remove users without having to make changes throughout the site. As you define more access rules for your application, roles become a more convenient way to apply the changes to groups of users.

Roles and Access Rules

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.

Role Management, User Identity, and Membership

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.

Role Management and the ASP.NET Roles Service

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 API

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.

How ASP.NET Role Management Works

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:

Roles.CreateRole("members")
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:

Roles.AddUserToRole("JoeWorden", "manager")
Dim userGroup(2) As String
userGroup(0) = "JillShrader"
userGroup(1) = "ShaiBassli"
Roles.AddUsersToRole(userGroup, "members")
Roles.AddUserToRole("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

At run time, when users visit your site, they establish an identity, either as a Windows account name or by logging into your application. (In an Internet site, if users visit your site without logging in (anonymously), they will have no user identity and therefore will not be in any role.) Information about the logged-in user is available to your application from the User property. When roles are enabled, ASP.NET looks up the roles for the current user and adds them to the User object so that you can check them. The following example shows how to determine whether the current user is in the role of member. If the user is in the role, the code displays a button for members:

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

ASP.NET also creates an instance of the RolePrincipal class and adds it to the current request context. This enables you to perform role management tasks programmatically, such as determining what users are in a specific role. . The following example shows how to obtain a list of the roles for the current logged-in user.

Dim userRoles() as String = CType(User, RolePrincipal).GetRoles()
string[] userRoles = ((RolePrincipal)User).GetRoles();

If you are using the LoginView control in your application, the control will check the user's roles and can dynamically create a user interface based on the user's roles.

Caching Role Information

If a user's browser allows cookies, ASP.NET can optionally store role information in an encrypted cookie on the user's computer. On each page request, ASP.NET reads the cookie and populates the role information for that user from the cookie. This strategy minimizes the need to read role information from the database. If the user's browser does not support cookies or if cookies are disabled, role information is instead cached only for the duration of each page request.

See Also

Concepts

Role Management Providers

Role Management Classes

Other Resources

ASP.NET Security