forms Element for authentication (ASP.NET Settings Schema)
Configures an ASP.NET application for custom forms–based authentication.
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>
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. NoteIn 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. ValueDescription UseCookiesSpecifies that cookies will always be used, regardless of the device. UseUriSpecifies that cookies will never be used. AutoDetectSpecifies 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. UseDeviceProfileSpecifies 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. NoteWhen 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. ValueDescription TrueSpecifies that authenticated users can be redirected to URLs in other Web applications. FalseSpecifies 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. ValueDescription AllSpecifies 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. EncryptionSpecifies 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. NoneSpecifies 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. ValidationSpecifies 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. ValueDescription TrueSpecifies 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. FalseSpecifies 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. ValueDescription TrueSpecifies that sliding expiration is enabled. The authentication cookie is refreshed and the time to expiration is reset on subsequent requests during a single session. FalseSpecifies 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. ValueDescription Framework20Specifies that the ticket expiration date is stored using local time. Framework40Specifies 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). NoteUnder 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. |
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>
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>
Configuration section handler | |
Configuration member | |
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 |
Note