<forms> Element

Article
10/23/2006

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

<configuration>
   <system.web>
      <authentication>
         <forms>

<forms name="name" 
       loginUrl="url"
       protection="All|None|Encryption|Validation"
       timeout="30"
       path="/" 
       requireSSL="true|false"
       slidingExpiration="true|false">
   <credentials passwordFormat="format"/>
</forms>

Optional Attributes

Attribute	Option	Description
name		Specifies the HTTP cookie to use for authentication. By default, the value of name is .ASPXAUTH. If multiple applications are running on a single server and each application requires a unique cookie, you must configure the cookie name in each application's Web.config file.
loginUrl		Specifies the URL to which the request is redirected for logon if no valid authentication cookie is found. The default value is default.aspx.
protection		Specifies the type of encryption, if any, to use for cookies.
	All	Specifies that the application uses both data validation and encryption to help protect the cookie. This option uses the configured data validation algorithm (based on the <machineKey> element). Triple-DES (3DES) is used for encryption, if available and if the key is long enough (48 bytes or more). All is the default (and recommended) value.
	None	Specifies that both encryption and validation are disabled for sites that are using cookies only for personalization and have weaker security requirements. Using cookies in this manner is not recommended; however, it is the least resource-intensive way to enable personalization using the .NET Framework.
	Encryption	Specifies that the cookie is encrypted using Triple-DES or DES, but data validation is not performed on the cookie. Cookies used in this way might be subject to chosen plaintext attacks.
	Validation	Specifies that a validation scheme verifies that the contents of an encrypted cookie have not been altered in transit. The cookie is created 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.
timeout		Specifies the amount of time, in integer minutes, after which the cookie expires. The default value is 30. If the SlidingExpiration attribute is true, the timeout attribute is a sliding value, expiring at the specified number of minutes after the time the last request was received. To prevent compromised performance, and to avoid multiple browser warnings for users that have cookie warnings turned on, the cookie is updated when more than half the specified time has elapsed. This might result in a loss of precision. Persistent cookies do not time out.
path		Specifies the path for cookies issued by the application. The default value is a slash (/), because most browsers are case-sensitive and will not send cookies back if there is a path case mismatch.
requireSSL		Specifies whether an SSL connection is required to transmit the authentication cookie.
	true	Specifies that an SSL connection is required to help protect the user's credentials. If true, ASP.NET sets HttpCookie.Secure for the authentication cookie and a compliant browser does not return the cookie unless the connection is using Secure Sockets Layer (SSL).
	false	Specifies that an SSL connection is not required to transmit the cookie. The default is false.
slidingExpiration		Specifies whether sliding expiration is enabled. Sliding expiration resets an active authentication cookie's time to expiration upon each request during a single session.
	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 version 1.0 of ASP.NET was true.
	false	Specifies that sliding expiration is not enabled and the cookie expires at a set interval from the time it was originally issued. The default is false.

Subtag

Subtag	Description
<credentials>	Allows definition 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.

Remarks

If multiple applications are running on a single server, the <forms> attributes must be configured in the Web.config file for each application.

Example

The following example configures 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">
            <credentials passwordFormat = "SHA1" 
               <user name="UserName" 
                     password="07B7F3EE06F278DB966BE960E7CBBD103DF30CA6"/>
            </credentials>
         </forms>
      </authentication>
   </system.web>
</configuration>

Requirements

Contained Within: <system.web>

Web Platform: IIS 5.0, IIS 5.1, IIS 6.0

Configuration File: Machine.config, Web.config

Configuration Section Handler: System.Web.Configuration.AuthenticationConfigHandler