forms Element for authentication (ASP.NET Settings Schema)

Article
04/30/2007

Configures an ASP.NET application for custom forms–based authentication.

<forms 
   name="name" 
   loginUrl="URL" 
   defaultUrl="URL"
   protection="[All|None|Encryption|Validation]"
   timeout="[MM]"
   path="path"
   requireSSL="[true|false]"
   slidingExpiration="[true|false]">
   enableCrossAppRedirects="[true|false]"
   cookieless="[UseUri|UseCookie|AutoDetect|UseDeviceProfile]" 
   domain="domain name">
   <credentials>...</credentials>
</forms>

Attributes and Elements

The following sections describe attributes, child elements, and parent elements.

Attributes

cookieless

Optional attribute.

Defines whether cookies are used and their behavior.

This attribute can be one of the following values.

Value	Description
UseCookies	Specifies that cookies will always be used, regardless of the device.
UseUri	Specifies that cookies will never be used.
AutoDetect	Specifies that cookies are used, if the device profile supports cookies; otherwise, cookies are not used. For desktop browsers that are known to support cookies, a probing mechanism will be used to try to use cookies, when enabled. If a device does not support cookies, no probing mechanism will be used.
UseDeviceProfile	Specifies that cookies are used, if the browser supports cookies; otherwise, cookies are not used. For devices that support cookies, no attempt is made to probe to determine whether cookie support is enabled.

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

The default is UseDeviceProfile.

defaultUrl

Optional attribute.

Defines the default URL that is used for redirection after authentication.

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

The default is "default.aspx".

domain

Optional attribute.

Specifies an optional domain to set on outgoing forms-authentication cookies. This setting takes precedence over the domain that is used in the httpCookies element.

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

The default is an empty string ("").

enableCrossAppRedirects

Optional attribute.

Indicates whether authenticated users are redirected to URLs in other Web applications.

Note

When performing redirects across applications, you must make sure that several of the attributes in the forms Element for authentication (ASP.NET Settings Schema) are duplicated across the authenticated applications. For more information and an example, see Forms Authentication Across Applications.

This attribute can be one of the following values.

Value	Description
True	Specifies that authenticated users can be redirected to URLs in other Web applications.
False	Specifies that authenticated users cannot be redirected to URLs in other Web applications.

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

The default is False.

loginUrl

Optional attribute.

Specifies the URL to which the request is redirected for logon, if no valid authentication cookie is found.

The default is login.aspx.

name

Optional attribute.

Specifies the HTTP cookie to use for authentication. If multiple applications are running on a single server and each application requires a unique cookie, you must configure the cookie name in each Web.config file for each application.

The default is ".ASPXAUTH".

path

Optional attribute.

Specifies the path for cookies that are issued by the application.

The default is a slash (/), because most browsers are case-sensitive and will not send cookies back, if there is a path case mismatch.

protection

Optional attribute.

Specifies the type of encryption, if any, to use for cookies.

This attribute can be one of the following values.

Value	Description
All	Specifies that the application uses both data validation and encryption to help protect the cookie. This option uses the configured data validation algorithm, which is based on the machineKey element. Triple-DES (3DES) is used for encryption, if it is available and if the key is long enough (48 bytes or more). All is the default, and recommended, value.
Encryption	Specifies that both encryption and validation are disabled for sites that are using cookies only for personalization and have less stringent security requirements. You should not use cookies in this manner; however, it is the least resource-intensive way to enable personalization in the .NET Framework.
None	Specifies that the cookie is encrypted by using 3DES or DES, but data validation is not performed on the cookie. Cookies used in this manner might be subject to chosen plain-text attacks.
Validation	Specifies that a validation scheme verifies that the contents of an encrypted cookie have not been changed in transit. The cookie is created by using cookie validation by concatenating a validation key with the cookie data, computing a message authentication code (MAC), and appending the MAC to the outgoing cookie.

The default is All.

requireSSL

Optional attribute.

Specifies whether an SSL connection is required to transmit the authentication cookie.

This attribute can be one of the following values.

Value	Description
True	Specifies that an SSL connection is required to help protect the user's credentials. If True, ASP.NET sets the Secure property for the authentication cookie and a compliant browser does not return the cookie, unless the connection is using SSL.
False	Specifies that an SSL connection is not required to transmit the cookie. The default is False.

The default is False.

slidingExpiration

Optional attribute.

Specifies whether sliding expiration is enabled. Sliding expiration resets the active authentication time for a cookie to expire upon each request during a single session.

This attribute can be one of the following values.

Value	Description
True	Specifies that sliding expiration is enabled. The authentication cookie is refreshed and the time to expiration is reset on subsequent requests during a single session. The default for the .NET Framework version 1.1 is True.
False	Specifies that sliding expiration is not enabled and the cookie expires at a set interval from the time the cookie was originally issued. The default for the .NET Framework version 2.0 is False.

The default is True for the .NET Framework version 1.1 and False for the .NET Framework version 2.0.

timeout

Optional attribute.

Specifies the time, in integer minutes, after which the cookie expires. If the SlidingExpiration attribute is true, the timeout attribute is a sliding value, expiring at the specified number of minutes after the time that the last request was received. To prevent compromised performance, and to avoid multiple browser warnings for users who have cookie warnings turned on, the cookie is updated when more than half of the specified time has elapsed. This might cause a loss of precision. The default is "30" (30 minutes).

Note

Under ASP.NET V1.1 persistent cookies do not time out, regardless of the setting of the timeout attribute. However, as of ASP.NET V2.0, persistent cookies do time out according to the timeout attribute.

Child Elements

Subtag	Description
credentials	Allows optional definitions of name and password credentials within the configuration file. You also can implement a custom password scheme to use an external source, such as a database, to control validation.

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 settings in a configuration file and contains configuration elements that configure ASP.NET Web applications and control how the applications behave.
authentication	Configures the ASP.NET authentication scheme that is used to identify users who view an ASP.NET application.

Remarks

The forms element configures an ASP.NET application for custom forms–based authentication. If multiple applications are running on a single server, the attributes of the forms element must be configured in the Web.config file for each application. For more information, see Forms Authentication Across Applications.

You can exceed the maximum size of the URI when you send the forms authentication ticket in the URI. If the combination of the anonymous identification ticket, forms authentication ticket, session ID, and user data is greater than the maximum permissible URI length, the request will fail with a 400-Bad Request error.

Default Configuration

The following default forms 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 in the .NET Framework version 2.0.

<forms 
   name=".ASPXAUTH" 
   loginUrl="login.aspx" 
   defaultUrl="default.aspx" 
   protection="All" 
   timeout="30" 
   path="/" 
   requireSSL="false" 
   slidingExpiration="true" 
   cookieless="UseDeviceProfile" domain="" 
   enableCrossAppRedirects="false">
   <credentials passwordFormat="SHA1" />
</forms>

The following default forms element is configured in the Machine.config file in the .NET Framework version 1.1.

<forms 
   name=".ASPXAUTH" 
   loginUrl="login.aspx" 
   protection="All"  
   timeout="30" 
   path="/" 
   requireSSL="false" 
   slidingExpiration="true">
   <credentials passwordFormat="SHA1"></credentials>
</forms>

The following default forms element is configured in the Machine.config file in the .NET Framework version 1.0.

<forms 
   name=".ASPXAUTH" 
   loginUrl="login.aspx" 
   protection="All"  
   timeout="30" 
   path="/" >
   <credentials passwordFormat="SHA1"></credentials>
</forms>

Example

The following code example demonstrates how to configure a site for forms–based authentication, specifies the name of the cookie that transmits logon information from the client, and specifies the name of the logon page to use, if initial authentication fails.

<configuration>
   <system.web>
   <authentication mode="Forms">
      <forms 
      name="401kApp" 
      loginUrl="/login.aspx"
      cookieless="AutoDetect"
      defaultUrl="myCustomLogin.aspx">
      <credentials passwordFormat = "SHA1">   
         <user name="UserName" 
         password="07B7F3EE06F278DB966BE960E7CBBD103DF30CA6"/>
      </credentials>   
      </forms>
   </authentication>
   </system.web>
</configuration>

Element Information

Configuration section handler	AuthenticationSection
Configuration member	FormsAuthentication FormsAuthenticationConfiguration
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 1.0, 1.1, or 2.0 Microsoft Visual Studio 2003 or Visual Studio 2005

Partager via

forms Element for authentication (ASP.NET Settings Schema)

Attributes and Elements

Attributes

Child Elements

Parent Elements

Remarks

Default Configuration

Example

Element Information

See Also

Tasks

Reference

Concepts

Other Resources

Ressources supplémentaires