Elemento forms para authentication (Esquema de configuración de ASP.NET)

Contraer todo

Filtro de lenguage

Ver contenido: en paralelo

.NET Framework 4

forms Element for authentication (ASP.NET Settings Schema)

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

Atributos

Atributo	Descripción
cookieless	Atributo opcional. Define si se utilizan cookies y su comportamiento. Este atributo puede tener uno de los siguientes valores. Nota En los sitios web ASP.NET habilitados para AJAX, utilice el valor predeterminado UseCookies para el atributo cookieless. Las bibliotecas de script de cliente AJAX de ASP.NET no admiten la configuración en la que se utilizan cookies codificadas en la dirección URL. ValorDescripción UseCookiesEspecifica que siempre se utilizarán cookies, independientemente del dispositivo. UseUriEspecifica que nunca se utilizarán cookies. AutoDetectEspecifica que se utilizan cookies si el perfil del dispositivo las admite; en caso contrario, no se utilizan cookies.En el caso de los exploradores de escritorio que admiten el uso de cookies, se utilizará un mecanismo de prueba para intentar utilizarlas cuando estén habilitadas. Si un dispositivo no admite cookies, no se utilizará este mecanismo de prueba. UseDeviceProfileEspecifica que se utilizan cookies si el explorador las admite; en caso contrario, no se utilizan cookies. En el caso de los dispositivos que admiten cookies, no se intenta determinar si está habilitado el uso de cookies. Este atributo es nuevo en la versión 2.0 de .NET Framework. El valor predeterminado es UseDeviceProfile..
defaultUrl	Atributo opcional. Define la dirección URL predeterminada que se utiliza para el redireccionamiento después de la autenticación. Este atributo es nuevo en la versión 2.0 de .NET Framework. El tipo predeterminado es "default.aspx".
domain	Atributo opcional. Especifica un dominio opcional que se va a establecer en las cookies de autenticación de los formularios salientes. Esta opción tiene prioridad sobre el dominio utilizado en el elemento httpCookies. Este atributo es nuevo en la versión 2.0 de .NET Framework. El valor predeterminado es una cadena vacía ("").
enableCrossAppRedirects	Atributo opcional. Indica si los usuarios autenticados se redirigen a direcciones URL en otras aplicaciones Web. Nota Al realizar redireccionamientos entre aplicaciones, se debe comprobar que varios de los atributos de Elemento forms para authentication (Esquema de configuración de ASP.NET) estén duplicados en las aplicaciones autenticadas. Para obtener más información y un ejemplo, vea Autenticación de formularios entre distintas aplicaciones. Este atributo puede tener uno de los siguientes valores. ValorDescripción TrueEspecifica que los usuarios autenticados pueden redirigirse a direcciones URL en otras aplicaciones Web. FalseEspecifica que los usuarios autenticados no pueden redirigirse a direcciones URL en otras aplicaciones Web. Este atributo es nuevo en la versión 2.0 de .NET Framework. El tipo predeterminado es False.
loginUrl	Atributo opcional. Especifica la dirección URL a la que debe redirigirse la solicitud de inicio de sesión si no se encuentra ninguna cookie de autenticación válida. El tipo predeterminado es login.aspx.
name	Atributo opcional. Especifica la cookie HTTP utilizada para la autenticación. Si se ejecutan varias aplicaciones en un mismo servidor y cada una requiere una cookie única, se debe configurar el nombre de la cookie en cada archivo Web.config de cada aplicación. El tipo predeterminado es ".ASPXAUTH".
path	Atributo opcional. Especifica la ruta de acceso de las cookies emitidas por la aplicación. El valor predeterminado es una barra diagonal (/), ya que la mayor parte de los exploradores distinguen mayúsculas y minúsculas, y no devolverán cookies si hay una discrepancia de este tipo en la ruta de acceso.
protection	Atributo opcional. Si se ha utilizado algún tipo de cifrado, especifica el empleado para las cookies. Este atributo puede tener uno de los siguientes valores. ValorDescripción AllEspecifica que la aplicación utiliza validación de datos y cifrado para ayudar a proteger la cookie. Esta opción utiliza el algoritmo de validación de datos configurado, que se basa en el elementomachineKey. Para el cifrado se utiliza Triple-DES (3DES), si está disponible y si la longitud de la clave es suficiente (48 bytes o más). All es el valor predeterminado y recomendado. EncryptionEspecifica que las cookies se cifran con 3DES o DES, pero que no se validan los datos en la cookie. Las cookies empleadas de esta manera pueden sufrir ataques en el texto sin formato. NoneEspecifica que tanto el cifrado como la validación están deshabilitados para aquellos sitios que utilizan cookies sólo para la personalización y tienen requisitos de seguridad menos estrictos Se recomienda no utilizar las cookies de esta manera; no obstante, es el método que menos recursos requiere para habilitar la personalización en .NET Framework. ValidationEspecifica que un esquema de validación comprueba que el contenido de una cookie cifrada no ha sido alterado durante el trayecto. La cookie se crea con validación de cookies mediante la concatenación de una clave de validación y los datos de la cookie, el cálculo de un código de autenticación de mensajes (MAC) y la anexión de este código a la cookie saliente. El tipo predeterminado es All.
requireSSL	Atributo opcional. Especifica si se requiere una conexión SSL para transmitir la cookie de autenticación. Este atributo puede tener uno de los siguientes valores. ValorDescripción TrueEspecifica que se requiere una conexión SSL para ayudar a proteger las credenciales del usuario. Si su valor es True, ASP.NET establece la propiedad Secure de la cookie de autenticación y un explorador compatible no devuelve la cookie, a menos que la conexión utilice SSL. FalseEspecifica que no se requiere una conexión SSL para transmitir la cookie. El tipo predeterminado es False. El tipo predeterminado es False.
slidingExpiration	Atributo opcional. Especifica si el plazo de expiración está habilitado. Este plazo restablece el tiempo del que dispone una cookie de autenticación activa hasta su expiración en cada solicitud realizada durante una sesión. Este atributo puede tener uno de los siguientes valores. ValorDescripción TrueEspecifica que el plazo de expiración está habilitado. La cookie de autenticación se actualiza y el tiempo hasta la expiración se restablece para las solicitudes siguientes realizadas en la misma sesión. FalseEspecifica que el plazo de expiración no está habilitado y que la cookie expira en un intervalo de tiempo fijado, a partir del momento en que se emitió originalmente. El valor predeterminado es True.
ticketCompatibilityMode	Atributo opcional. Especifica si se va a usar la Hora universal coordinada (UTC) o la hora local para la fecha de expiración del vale para la autenticación de formularios. Este atributo puede TENER uno de los siguientes valores. ValorDescripción Framework20Especifica que la fecha de expiración del vale se almacena utilizando la hora local. Framework40Especifica que la fecha de expiración del vale se almacena utilizando la hora UTC. El valor predeterminado es Framework20.
timeout	Atributo opcional. Especifica el intervalo de tiempo, en minutos enteros, transcurrido el cual la cookie expira. Si el valor del atributo SlidingExpiration es true, el atributo timeout es un valor variable, que expira cuando transcurre el número de minutos especificado, contados a partir de la recepción de la última solicitud. Para evitar problemas de rendimiento y evitar que aparezcan numerosas advertencias del explorador a los usuarios que tengan activadas las advertencias de cookies, la cookie se actualiza cuando ha transcurrido más de la mitad del tiempo especificado. Esto puede disminuir la precisión. El valor predeterminado es "30" (30 minutos). Nota En ASP.NET 1.1, las cookies persistentes no expiran, sea cual sea el valor del atributo de tiempo de espera. Sin embargo, a partir de ASP.NET 2.0, las cookies persistentes expiran según el valor del atributo de tiempo de espera.

Elementos secundarios

Subetiqueta	Descripción
credentials	Permite las definiciones opcionales de las credenciales de nombre y contraseña en el archivo de configuración. También puede implementar un esquema personalizado de contraseñas que use un origen externo, por ejemplo una base de datos, para controlar la validación.

Elementos primarios

Elemento	Descripción
configuration	Especifica el elemento raíz necesario de cada archivo de configuración que utilizan las aplicaciones basadas en Common Language Runtime y .NET Framework.
system.web	Especifica el elemento raíz de los valores de configuración de ASP.NET en un archivo de configuración y contiene elementos de configuración que configuran aplicaciones Web ASP.NET y controlan el comportamiento de las aplicaciones.
authentication	Configura el esquema de autenticación de ASP.NET utilizado para identificar usuarios que ven una aplicación ASP.NET.

Comentarios

El elemento forms configura una aplicación ASP.NET para una autenticación personalizada basada en formularios. Si se ejecutan varias aplicaciones en un único servidor, los atributos del elemento forms se deben configurar en el archivo Web.config de cada aplicación. Para obtener más información, vea Autenticación de formularios entre distintas aplicaciones.

Se puede superar el tamaño máximo del identificador URI cuando se envía el vale de autenticación de los formularios en el identificador URI. Si la combinación del vale de identificación anónimo, el vale de autenticación de los formularios, el identificador de sesión y los datos de usuario es mayor que la longitud máxima permitida del identificador URI, se generará el error 400 de solicitud incorrecta.

Configuración predeterminada

El siguiente elemento forms predeterminado no se configura explícitamente en el archivo Machine.config o en el archivo Web.config raíz. Sin embargo, es la configuración predeterminada que devuelve la aplicación en .NET Framework 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>

En .NET Framework 1.1, el siguiente elemento forms predeterminado se configura en el archivo Machine.config.

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

En .NET Framework 1.0, el siguiente elemento forms predeterminado se configura en el archivo Machine.config.

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

Ejemplo

En el siguiente ejemplo de código se muestra cómo configurar un sitio para la autenticación basada en formularios, se especifica el nombre de la cookie que transmite la información de inicio de sesión del cliente y se especifica el nombre de la página de inicio de sesión que se va a utilizar si se genera un error en la autenticación inicial.

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

Información de elemento

Controlador de la sección de configuración	AuthenticationSection
Miembro de configuración	FormsAuthentication FormsAuthenticationConfiguration
Ubicaciones configurables	Machine.config Web.config del nivel raíz Web.config del nivel de aplicaciones
Requisitos	Microsoft Internet Information Services (IIS) 5.0, 5.1 ó 6.0 .NET Framework versión 1.0, 1.1 ó 2.0 Microsoft Visual Studio 2003 o Visual Studio 2005