roleManager Element (ASP.NET Settings Schema)

Configures an application for role management.

This element is new in the .NET Framework version 2.0.

<roleManager
    cacheRolesInCookie="true|false"
    cookieName="name"
    cookiePath="/"
    cookieProtection="All|Encryption|Validation|None"
    cookieRequireSSL="true|false "
    cookieSlidingExpiration="true|false "
    cookieTimeout="number of minutes"
    createPersistentCookie="true|false"
    defaultProvider="provider name"
    domain="cookie domain">
    enabled="true|false"
    maxCachedResults="maximum number of role names cached"
    <providers>...</providers>
</roleManager>

Attributes and Elements

The following sections describe attributes, child elements, and parent elements for this section.

Attributes

Attribute	Description
cacheRolesInCookie	Optional Boolean attribute. Specifies that when validating that a user is in a particular role, the cookie is checked before using the role provider to check the list of roles at the data source. If true, a list of role names in a cookie is cached for the current user; otherwise, false. The default is false.
cookieName	Optional String attribute. Specifies the name of the cookie in which role names are stored. The default is ".ASPXROLES".
cookiePath	Optional String attribute. The path for the role names cookie. The default is "/".
cookieProtection	Optional CookieProtection attribute. Specifies one of the CookieProtection enumeration values. The default is the All value.
cookieRequireSSL	Optional Boolean attribute. Specifies whether the role names cookie requires SSL to be setn to the server. If set to true, role names cookies require SSL to be sent to the server. The default is false.
cookieSlidingExpiration	Optional Boolean attribute. Specifies whether the expiration date and time of the role names cookie will be reset periodically. If set to true, the cookie expiration will at first be set to the current date and time plus the CookieTimeout value, in minutes. While the user continues to actively use the ASP.NET application, the expiration date and time of the cookie is automatically updated, if there is less than half of the CookieTimeout value remaining. For more information, see Expires. The default is true.
cookieTimeout	Optional Int32 attribute. The number of minutes before the role names cookie expires. The default is "30" (minutes).
createPersistentCookie	Optional Boolean attribute. Specifies whether the role names cookie is a session cookie; that is, the cookie is lost when the browser is closed. When set to true, the role names cookie is a persistent cookie that is available across multiple browser sessions. The persistent cookie expiration date and time are set to the current date and time plus the CookieTimeout value, in minutes. The default is false.
defaultProvider	Optional String attribute. The name of the default role provider. For more information, see Provider. The default is "AspNetSqlRoleProvider".
domain	Optional String attribute. Specifies the Domain value of the role names cookie. The default is the HttpCookie property default, which is an empty string ("").
enabled	Optional Boolean attribute. Specifies whether to enable role management. When set to true, role management is enabled. The default is false in the Machine.config file.
maxCachedResults	Optional Int32 attribute. Specifies the maximum number of role names that are cached in the roles cookie. The default is 25.
Inherited attributes	Optional attributes. Attributes inherited by all section elements. For more information, see General Attributes Inherited by Section Elements.

Child Elements

Element	Description
providers	Optional element. Defines a collection of role providers for role management.

Parent Elements

Element	Description
configuration	Specifies the required root element in every configuration file that is used by the common language runtime and the .NET Framework applications.
system.web	Specifies the root element for the ASP.NET configuration section.

Remarks

The roleManager element configures an application for role management.

For information about accessing and modifying configuration values for the roleManager element in application code, see RoleManagerSection.

Default Configuration

The following default roleManager element is not explicitly configured in the Machine.config file or in the root Web.config file. However, it is the default configuration that is returned by the application. The providers are explicitly configured in the Machine.config file.

<roleManager 
   enabled="false" 
   cacheRolesInCookie="false" 
   cookieName=".ASPXROLES" 
   cookieTimeout="30" 
   cookiePath="/" 
   cookieRequireSSL="false" 
   cookieSlidingExpiration="true" 
   cookieProtection="All" 
   defaultProvider="AspNetSqlRoleProvider" 
   createPersistentCookie="false" 
   maxCachedResults="25">
   <providers>
      <clear />
      <add 
         connectionStringName="LocalSqlServer" 
         applicationName="/" 
         name="AspNetSqlRoleProvider" 
         type="System.Web.Security.SqlRoleProvider, System.Web, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" />
      <add 
         applicationName="/" 
         name="AspNetWindowsTokenRoleProvider" 
         type="System.Web.Security.WindowsTokenRoleProvider, System.Web, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" />
   </providers>
</roleManager>

Example

The following code example shows how to configure an ASP.NET application to use the SqlRoleProvider class to store and retrieve role information.

<configuration>
  <system.web>
    <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>

Element Information

Configuration section handler	RoleManagerSection
Configuration member	RoleManager
Configurable locations	Machine.config Root-level Web.config Application-level Web.config
Requirements	Microsoft Internet Information Services (IIS) version 5.0, 5.1, or 6.0 The .NET Framework version 2.0 Microsoft Visual Studio 2003 or Visual Studio 2005

See Also

Tasks

How to: Configure Specific Directories Using Location Settings
How to: Lock ASP.NET Configuration Settings

Reference

system.web Element (ASP.NET Settings Schema)
providers Element for roleManager (ASP.NET Settings Schema)
configuration Element (General Settings Schema)
System.Configuration
System.Web.Configuration
RoleManagerSection
RoleManager

Concepts

Understanding ASP.NET Role Management
Securing ASP.NET Configuration
ASP.NET Configuration Scenarios

Other Resources

General Configuration Settings (ASP.NET)
ASP.NET Configuration Settings
ASP.NET Reference
Configuring ASP.NET Applications
ASP.NET Configuration API