Share via

roleManager Element (ASP.NET Settings Schema)

  • Article

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