Export (0) Print
Expand All
1 out of 4 rated this helpful - Rate this topic

Roles Class

Manages user membership in roles for authorization checking in an ASP.NET application. This class cannot be inherited.

System.Object
  System.Web.Security.Roles

Namespace:  System.Web.Security
Assembly:  System.Web (in System.Web.dll)
public static class Roles

The Roles type exposes the following members.

  NameDescription
Public propertyStatic memberApplicationNameGets or sets the name of the application to store and retrieve role information for.
Public propertyStatic memberCacheRolesInCookieGets a value indicating whether the current user's roles are cached in a cookie.
Public propertyStatic memberCookieNameGets the name of the cookie where role names are cached.
Public propertyStatic memberCookiePathGets the path for the cached role names cookie.
Public propertyStatic memberCookieProtectionValueGets a value that indicates how role names cached in a cookie are protected.
Public propertyStatic memberCookieRequireSSLGets a value indicating whether the role names cookie requires SSL in order to be returned to the server.
Public propertyStatic memberCookieSlidingExpirationIndicates whether the role names cookie expiration date and time will be reset periodically.
Public propertyStatic memberCookieTimeoutGets the number of minutes before the roles cookie expires.
Public propertyStatic memberCreatePersistentCookieGets a value indicating whether the role-names cookie is session-based or persistent.
Public propertyStatic memberDomainGets the value of the domain of the role-names cookie.
Public propertyStatic memberEnabledGets or sets a value indicating whether role management is enabled for the current Web application.
Public propertyStatic memberMaxCachedResultsGets the maximum number of role names to be cached for a user.
Public propertyStatic memberProviderGets the default role provider for the application.
Public propertyStatic memberProvidersGets a collection of the role providers for the ASP.NET application.
Top
  NameDescription
Public methodStatic memberAddUsersToRoleAdds the specified users to the specified role.
Public methodStatic memberAddUsersToRolesAdds the specified users to the specified roles.
Public methodStatic memberAddUserToRoleAdds the specified user to the specified role.
Public methodStatic memberAddUserToRolesAdds the specified user to the specified roles.
Public methodStatic memberCreateRoleAdds a new role to the data source.
Public methodStatic memberDeleteCookieDeletes the cookie where role names are cached.
Public methodStatic memberDeleteRole(String)Removes a role from the data source.
Public methodStatic memberDeleteRole(String, Boolean)Removes a role from the data source.
Public methodStatic memberFindUsersInRoleGets a list of users in a specified role where the user name contains the specified user name to match.
Public methodStatic memberGetAllRolesGets a list of all the roles for the application.
Public methodStatic memberGetRolesForUser()Gets a list of the roles that the currently logged-on user is in.
Public methodStatic memberGetRolesForUser(String)Gets a list of the roles that a user is in.
Public methodStatic memberGetUsersInRoleGets a list of users in the specified role.
Public methodStatic memberIsUserInRole(String)Gets a value indicating whether the currently logged-on user is in the specified role.
Public methodStatic memberIsUserInRole(String, String)Gets a value indicating whether the specified user is in the specified role.
Public methodStatic memberRemoveUserFromRoleRemoves the specified user from the specified role.
Public methodStatic memberRemoveUserFromRolesRemoves the specified user from the specified roles.
Public methodStatic memberRemoveUsersFromRoleRemoves the specified users from the specified role.
Public methodStatic memberRemoveUsersFromRolesRemoves the specified user names from the specified roles.
Public methodStatic memberRoleExistsGets a value indicating whether the specified role name already exists in the role data source.
Top

ASP.NET role management enables you to manage authorization for your application based on groups of users, referred to as roles. By assigning users to roles, you can control access to different parts or features of your Web application based on role instead of, or in addition to, specifying authorization based on user name. For example, an employee application might have roles such as Managers, Employees, Directors, and so on, where different privileges are specified for each role.

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

To enable role management for your ASP.NET application, use the roleManager element of the system.web section in the Web.config file for your application, as shown in the following example.

<configuration>
  <connectionStrings>
    <add name="SqlServices" connectionString="Data Source=localhost;Initial Catalog=aspnetdb;Integrated Security=SSPI;" />
  </connectionStrings>

  <system.web>
    <authentication mode="Forms" >
      <forms loginUrl="login.aspx"
      name=".ASPXFORMSAUTH" />
    </authentication>

  <roleManager defaultProvider="SqlProvider" 
    enabled="true"
    cacheRolesInCookie="true"
    cookieName=".ASPROLES"
    cookieTimeout="30"
    cookiePath="/"
    cookieRequireSSL="false"
    cookieSlidingExpiration="true"
    cookieProtection="All" >
    <providers>
      <add
        name="SqlProvider"
        type="System.Web.Security.SqlRoleProvider"
        connectionStringName="SqlServices"
        applicationName="SampleApplication" />
      </providers>
    </roleManager>
  </system.web>
</configuration>

You can specify authorization rules in the configuration file for your Web application or programmatically in your code. For example, the following authorization section from a Web.config file requires users to log on (by denying anonymous users), and then allows only users in the Administrators role to have access.

<authorization>
  <deny users="?" />
  <allow roles="Administrators" />
  <deny users="*" />
</authorization>

If you use the authorization section in your application's Web.config file to specify authorization based on roles, users of your application must supply an authenticated user identity. You can authenticate users by using either Windows or Forms authentication. Anonymous users cannot be assigned to a role. Roles can be used independently of, or in conjunction with, the ASP.NET Membership classes.

To verify role membership programmatically, you can use the Roles class or the Page.User property with the IsUserInRole method, or you can use the Page.User property with the IPrincipal.IsInRole method. For sample code that programmatically checks role membership, see the Example section in this topic.

The Roles class also enables you to create and delete roles and to add users to or remove users from roles.

NoteNote

If you have configured your application to use the WindowsTokenRoleProvider class, you cannot modify roles or role membership. The WindowsTokenRoleProvider class verifies membership in Windows security groups only. In this case, you must use Windows user account management rather than ASP.NET roles to create and delete groups and manage group membership.

You can store role information in several data sources.

  • You can use the WindowsTokenRoleProvider class to retrieve role information based on membership in Windows groups.

  • You can store role information in a SQL Server database by using the SqlRoleProvider class.

  • If you have existing role information, or want to store role information in and retrieve role information from a data source other than Windows, an Authorization Store, or SQL Server, you can implement a custom role provider by creating a class that inherits the RoleProvider abstract class. For more information, see Implementing a Role Provider.

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 data source to retrieve role information. If the role information for a user is too long to store in a cookie, ASP.NET stores just the most recently used role information in the cookie and then looks up additional role information in the data source as required. If the user's browser does not support cookies or cookies are disabled, role information is not cached in a cookie.

You can improve the reliability of the role names cached in a cookie by specifying a CookieProtectionValue property when you configure ASP.NET roles. The default CookieProtectionValue is All, which encrypts role names in the cookie and validates that the cookie contents have not been altered.

TopicLocation
How to: Sample Role-Provider ImplementationBuilding ASP .NET Web Applications
How to: Sample Role-Provider ImplementationBuilding ASP .NET Web Applications

The following example shows the Web.config file for an application configured to use both ASP.NET membership and ASP.NET roles and to use the SqlRoleProvider to store membership and role information in a SQL Server database. Users are authenticated with forms authentication and only users in the Administrators role are allowed access to the application.

<configuration>
  <connectionStrings>
    <add name="SqlServices" connectionString="Data Source=localhost;Initial Catalog=aspnetdb;Integrated Security=SSPI;" />
  </connectionStrings>

  <system.web>
    <authentication mode="Forms" >
      <forms loginUrl="login.aspx"
      name=".ASPXFORMSAUTH" />
    </authentication>

    <authorization>
      <deny users="?" />
      <allow roles="Administrators" />
      <deny users="*" />
    </authorization>

    <membership defaultProvider="AspNetSqlProvider" userIsOnlineTimeWindow="15">
    </membership>

    <roleManager defaultProvider="SqlProvider" 
      enabled="true"
      cacheRolesInCookie="true"
      cookieName=".ASPROLES"
      cookieTimeout="30"
      cookiePath="/"
      cookieRequireSSL="true"
      cookieSlidingExpiration="true"
      cookieProtection="All" >

      <providers>
        <clear />
        <add
          name="SqlProvider"
          type="System.Web.Security.SqlRoleProvider"
          connectionStringName="SqlServices"
          applicationName="SampleApplication" />
        </providers>

    </roleManager>
  </system.web>
</configuration>

The following code example programmatically checks whether the logged-on user is in the Administrators role before allowing the user to view other users' roles.

.NET Framework

Supported in: 4.5.1, 4.5, 4, 3.5, 3.0, 2.0

Windows Phone 8.1, Windows Phone 8, Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.
Show:
© 2014 Microsoft. All rights reserved.