forms Element for authentication (ASP.NET Settings Schema)

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

configuration Element (General Settings Schema)
  system.web Element (ASP.NET Settings Schema)
    authentication Element (ASP.NET Settings Schema)
      forms Element for authentication (ASP.NET Settings Schema)

<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|UseCookies|AutoDetect|UseDeviceProfile]" 
   domain="domain name"
   ticketCompatibilityMode="[Framework20|Framework40]">
   <credentials>...</credentials>
</forms>

Attributes and Elements

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

Attributes

Attribute

Description

cookieless

Optional attribute.

Defines whether cookies are used and their behavior.

This attribute can be one of the following values.

Note

In AJAX-enabled ASP.NET Web sites, use the default value UseCookies for the cookieless attribute. Settings that use cookies encoded in the URL are not supported by the ASP.NET AJAX client-script libraries.

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 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.

None

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.

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.

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 is True.

ticketCompatibilityMode

Optional attribute.

Specifies whether to use Coordinated Universal Time (UTC) or local time for the ticket expiration date for forms authentication.

This attribute can HAVE one of the following values.

Value

Description

Framework20

Specifies that the ticket expiration date is stored using local time.

Framework40

Specifies that the ticket expiration date is stored using UTC.

The default value is Framework20.

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

See Also

Tasks

How to: Configure Specific Directories Using Location Settings

How to: Lock ASP.NET Configuration Settings

Reference

authentication Element (ASP.NET Settings Schema)

credentials Element for forms for authentication (ASP.NET Settings Schema)

system.web Element (ASP.NET Settings Schema)

passport Element for authentication (ASP.NET Settings Schema)

configuration Element (General Settings Schema)

System.Configuration

System.Web.Configuration

AuthenticationSection

FormsAuthentication

Concepts

Forms Authentication Across Applications

ASP.NET Configuration File Hierarchy and Inheritance

Securing ASP.NET Configuration

ASP.NET Configuration Scenarios

Other Resources

ASP.NET Authentication

General Configuration Settings (ASP.NET)

ASP.NET Configuration Settings

ASP.NET Web Site Administration

ASP.NET Configuration Files

ASP.NET Configuration API