authentication 的 forms 元素（ASP.NET 设置架构）

.NET Framework 常规参考

更新：2007 年 11 月

配置 ASP.NET 应用程序以执行基于窗体的自定义身份验证。

configuration 元素（常规设置架构）
  system.web 元素（ASP.NET 设置架构）
    authentication 元素（ASP.NET 设置架构）
      authentication 的 forms 元素（ASP.NET 设置架构）

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

属性和元素

下面几部分描述了属性、子元素和父元素。

属性

说明

cookieless

可选的属性。

定义是否使用 Cookie 以及 Cookie 的行为。

此属性可以为下列值之一。

说明：
当配置支持 AJAX 的 ASP.NET 网站时，应仅为 cookieless 属性使用 UseCookies 的默认值。ASP.NET AJAX 客户端脚本库不支持其他使用编码到 URL 中的 Cookie 的设置。

值	说明
UseCookies	指定无论在什么设备上都始终使用 Cookie。
UseUri	指定从不使用 Cookie。
AutoDetect	如果设备配置文件支持 Cookie，则指定使用 Cookie；否则不使用 Cookie。对于已知支持 Cookie 的桌面浏览器，将使用探测机制来尝试在启用 Cookie 时使用 Cookie。如果设备不支持 Cookie，将不使用探测机制。
UseDeviceProfile	如果浏览器支持 Cookie，则指定使用 Cookie；否则不使用 Cookie。对于支持 Cookie 的设备，不尝试通过探测来确定是否已启用 Cookie 支持。

此属性是 .NET Framework 2.0 版中的新属性。

默认值为 UseDeviceProfile.

defaultUrl

可选的属性。

定义在身份验证之后用于重定向的默认 URL。

此属性是 .NET Framework 2.0 版中的新属性。

默认值为 "default.aspx"。

domain

可选的属性。

指定在传出 Forms 身份验证 Cookie 中设置的可选域。此设置的优先级高于 httpCookies 元素中使用的域。

此属性是 .NET Framework 2.0 版中的新属性。

默认值为空字符串 ("")。

enableCrossAppRedirects

可选的属性。

表明是否将通过身份验证的用户重定向到其他 Web 应用程序中的 URL。

说明：
在跨应用程序执行重定向时，必须确保跨越已通过身份验证的应用程序复制 authentication 的 forms 元素（ASP.NET 设置架构）中的几个属性。有关更多信息及示例，请参见跨应用程序进行 Forms 身份验证。

此属性可以为下列值之一。

Value	说明
True	指定能够将通过身份验证的用户重定向到其他 Web 应用程序中的 URL。
False	指定不能将通过身份验证的用户重定向到其他 Web 应用程序中的 URL。

此属性是 .NET Framework 2.0 版中的新属性。

默认值为 False。

loginUrl

可选的属性。

指定如果找不到任何有效的身份验证 Cookie，将请求重定向到的用于登录的 URL。

默认值为 login.aspx。

name

可选的属性。

指定要用于身份验证的 HTTP Cookie。如果正在一台服务器上运行多个应用程序并且每个应用程序都需要唯一的 Cookie，则必须在每个应用程序的 Web.config 文件中配置 Cookie 名称。

默认值为 ".ASPXAUTH"。

path

可选的属性。

为应用程序发出的 Cookie 指定路径。

默认值是斜杠 (/)，这是因为大多数浏览器是区分大小写的，如果路径大小写不匹配，浏览器不会送回 Cookie。

protection

可选的属性。

指定 Cookie 使用的加密类型（如果有）。

此属性可以为下列值之一。

值	说明
All	指定应用程序同时使用数据验证和加密方法来保护 Cookie。该选项使用已配置的数据验证算法，该算法基于 machineKey 元素。如果三重 DES (3DES) 可用并且密钥足够长（48 位或更长），则使用三重 DES 进行加密。默认值（建议值）为 All。
Encryption	指定对于将 Cookie 仅用于个性化并且具有较低的安全要求的站点，同时禁用加密和验证。请不要以此方式使用 Cookie；但是，通过这种方法在 .NET Framework 中启用个性化占用的资源最少。
None	指定使用 3DES 或 DES 对 Cookie 进行加密，但不对 Cookie 执行数据验证。采用这种方式的 Cookie 可能受到精选的纯文本的攻击。
Validation	指定验证方案验证已加密的 Cookie 的内容在转换中是否未被更改。Cookie 是使用 Cookie 验证创建的，方法是：将验证密钥与 Cookie 数据相连接，然后计算消息身份验证代码 (MAC)，最后将 MAC 追加到传出 Cookie。

默认值为 All。

requireSSL

可选的属性。

指定是否需要 SSL 连接来传输身份验证 Cookie。

此属性可以为下列值之一。

值	说明
True	指定必须使用 SSL 连接来保护用户凭据。如果为 True，则 ASP.NET 为身份验证 Cookie 设置 Secure 属性，并且除非连接使用 SSL，否则兼容的浏览器不会返回 Cookie。
False	指定不要求使用 SSL 连接来传输 Cookie。默认值为 False。

默认值为 False。

slidingExpiration

可选的属性。

指定是否启用可调过期时间。可调过期将 Cookie 的当前身份验证时间重置为在单个会话期间收到每个请求时过期。

此属性可以为下列值之一。

值	说明
True	指定启用可调过期时间。在单个会话期间，身份验证 Cookie 被刷新，并且每个后续请求的到期时间被重置。
False	指定不启用可调过期，并指定 Cookie 在最初发出之后，经过一段设定的时间间隔后过期。

默认值为 True。

timeout

可选的属性。

指定 Cookie 过期前逝去的时间（以整数分钟为单位）。如果 SlidingExpiration 属性为 true，则 timeout 属性是滑动值，会在接收到上一个请求之后的指定时间（以分钟为单位）后过期。为防止危及性能并避免向开启 Cookie 警告的用户发出多个浏览器警告，当指定的时间逝去大半时将更新 Cookie。这可能导致精确性受损。默认值为 "30"（30 分钟）。

说明：
在 ASP.NET V1.1 下，无论超时属性的设置如何，持久性 Cookie 都不会超时。但是，从 ASP.NET V2.0 起，根据超时属性的设置，持久性 Cookie 会超时。

子元素

子标记	说明
credentials	允许选择在配置文件中定义名称和密码凭据。您还可以实现自定义的密码架构，以使用外部源（如数据库）来控制验证。

父元素

元素	说明
configuration	指定公共语言运行库和 .NET Framework 应用程序所使用的每个配置文件中均需要的根元素。
system.web	指定配置文件中 ASP.NET 配置设置的根元素，并包含用于配置 ASP.NET Web 应用程序和控制应用程序行为方式的配置元素。
authentication	配置 ASP.NET 身份验证方案，该方案用于识别查看 ASP.NET 应用程序的用户。

备注

forms 元素为基于窗体的自定义身份验证配置 ASP.NET 应用程序。如果在单个服务器上正运行多个应用程序，则必须在每个应用程序的 Web.config 文件中配置 forms 元素的属性。有关更多信息，请参见跨应用程序进行 Forms 身份验证。

在 URI 中发送 Forms 身份验证票时，可以超过 URI 的最大大小。如果匿名标识票证、Forms 身份验证票证、会话 ID 和用户数据的组合超过了允许的最大 URI 长度，请求将失败，并发出“400 错误的请求”错误。

默认配置

下面的默认 forms 元素不是在 Machine.config 文件或根 Web.config 文件中显式配置的。但它是 .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>

下面的默认 forms 元素在 .NET Framework 1.1 版的 Machine.config 文件中配置。

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

下面的默认 forms 元素在 .NET Framework 1.0 版的 Machine.config 文件中配置。

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

示例

下面的代码示例演示如何为基于窗体的身份验证配置站点、指定传输来自客户端的登录信息的 Cookie 的名称以及指定当初始身份验证失败时使用的登录页的名称。

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

元素信息

配置节处理程序	AuthenticationSection
配置成员	FormsAuthentication FormsAuthenticationConfiguration
可配置的位置	Machine.config 根级别的 Web.config 应用程序级别的 Web.config
要求	Microsoft Internet 信息服务 (IIS) 版本 5.0、5.1 或 6.0 .NET Framework 版本 1.0、1.1 或 2.0 Microsoft Visual Studio 2003 或 Visual Studio 2005

请参见

属性

子元素

父元素

默认配置

任务

概念

参考

其他资源