Apache 模块 mod_auth_form

Description:Form authentication
Status:Base
Module Identifier:auth_form_module
Source File:mod_auth_form.c
Compatibility:在 Apache 2.3 和更高版本中可用

Summary

Warning

表单身份验证取决于mod_session模块，并且这些模块使用 HTTP cookie，因此可能成为跨站点脚本攻击的受害者，或者向 Client 端公开潜在的私人信息。在服务器上启用会话功能之前，请确保已考虑到相关风险。

该模块允许使用 HTML 登录表单来通过在给定提供者中查找用户来限制访问。 HTML 表单比其他表单需要更多的配置，但是 HTML 登录表单可以为最终用户提供更友好的体验。

mod_auth_basic提供 HTTP 基本认证，而mod_auth_digest提供 HTTP 摘要认证。该模块应与至少一个认证模块(如mod_authn_file)和一个授权模块(如mod_authz_user)组合。

成功验证用户身份后，该用户的登录详细信息将存储在mod_session提供的会话中。

Basic Configuration

要使用mod_auth_form保护特定的 URL，您需要确定会话的存储位置，还需要确定将使用哪种方法进行身份验证。在此简单示例中，登录详细信息将存储在基于mod_session_cookie的会话中，并使用mod_authn_file尝试对文件进行身份验证。如果认证失败，则用户将被重定向到表单登录页面。

Basic example

<Location "/admin">
    AuthFormProvider file
    AuthUserFile "conf/passwd"
    AuthType form
    AuthName "/admin"
    AuthFormLoginRequiredLocation "http://example.com/login.html"

    Session On
    SessionCookieName session path=/

    Require valid-user
</Location>

设置为值形式时，伪指令AuthType将启用mod_auth_form身份验证。指令AuthFormProvider和AuthUserFile指定应对照所选文件检查用户名和密码。

指令Session和SessionCookieName会话存储在浏览器的 HTTP cookie 中。有关配置会话的不同选项的更多信息，请阅读mod_session的文档。

您可以选择添加SessionCryptoPassphrase来创建加密的会话 cookie。这需要加载附加模块mod_session_crypto。

在上面的简单示例中，URL 受mod_auth_form保护，但是尚未为用户提供 Importing 其用户名和密码的机会。这样做的选项包括为此目的提供专用的独立登录页面，或内联提供登录页面。

Standalone Login

登录表单可以作为独立页面托管，也可以内嵌在同一页面上。

当将登录配置为独立页面时，应使用AuthFormLoginRequiredLocation伪指令将失败的身份验证尝试重定向到网站为此目的创建的登录表单。通常，此登录页面将包含 HTML 表单，要求用户提供其使用名和密码。

登录表单示例

<form method="POST" action="/dologin.html">
  Username: <input type="text" name="httpd_username" value="" />
  Password: <input type="password" name="httpd_password" value="" />
  <input type="submit" name="login" value="Login" />
</form>

进行实际登录的部分由 form-login-handler 处理。表单的操作应指向此处理程序，该处理程序在 Apache httpd 中进行如下配置：

表单登录处理程序示例

<Location "/dologin.html">
    SetHandler form-login-handler
    AuthFormLoginRequiredLocation "http://example.com/login.html"
    AuthFormLoginSuccessLocation "http://example.com/admin/index.html"
    AuthFormProvider file
    AuthUserFile "conf/passwd"
    AuthType form
    AuthName /admin
    Session On
    SessionCookieName session path=/
</Location>

AuthFormLoginRequiredLocation伪指令指定的 URL 通常将指向一个页面，该页面向用户说明他们的登录尝试失败，因此应再次尝试。 AuthFormLoginSuccessLocation指令指定成功登录后应将用户重定向到的 URL。

或者，可以将成功重定向用户的 URL 嵌入在登录表单中，如下例所示。结果，可以将同一表单登录处理程序重新用于网站的不同区域。

带有位置的示例登录表单

<form method="POST" action="/dologin.html">
  Username: <input type="text" name="httpd_username" value="" />
  Password: <input type="password" name="httpd_password" value="" />
  <input type="submit" name="login" value="Login" />
  <input type="hidden" name="httpd_location" value="http://example.com/success.html" />
</form>

Inline Login

Warning

在某些情况下，存在使用内联登录配置的登录表单可能会多次提交的风险，从而向其下运行的应用程序显示登录凭据。Management 员必须确保适当保护基础应用程序，以防止滥用。如有疑问，请使用独立登录配置。

作为网站专用登录页面的替代方法，可以将mod_auth_form配置为内联身份验证用户，而无需重定向到另一个页面。这允许在登录尝试期间保留当前页面的状态。在有时间限制的会话生效并且会话在用户请求中间超时的情况下，这很有用。可以在适当位置重新验证用户，然后他们可以从中断的地方 continue 进行。

如果未经身份验证的用户尝试访问未使用AuthFormLoginRequiredLocation指令配置的受mod_auth_form保护的页面，则会将 HTTP_UNAUTHORIZED 状态代码返回给浏览器，以指示该用户无权查看该页面。

要配置内联身份验证，Management 员将使用包含登录表单的自定义错误文档覆盖 HTTP_UNAUTHORIZED 状态代码返回的错误文档，如下所示：

基本内联示例

AuthFormProvider file
ErrorDocument 401 "/login.shtml"
AuthUserFile "conf/passwd"
AuthType form
AuthName realm
AuthFormLoginRequiredLocation "http://example.com/login.html"
Session On
SessionCookieName session path=/

错误文档页面应包含一个带有空 action 属性的登录表单，如以下示例所示。这样可以将表单提交到原始受保护的 URL，而页面不必知道该 URL 是什么。

内联登录表单示例

<form method="POST" action="">
  Username: <input type="text" name="httpd_username" value="" />
  Password: <input type="password" name="httpd_password" value="" />
  <input type="submit" name="login" value="Login" />
</form>

最终用户填写了登录详细信息后，该表单将向原始受密码保护的 URL 发出 HTTP POST 请求。 mod_auth_form将拦截此 POST 请求，并且如果发现用户名和密码的 HTML 字段存在，则用户将登录，原始的受密码保护的 URL 将作为 GET 请求返回给用户。

内联登录并保留身体

上述内联登录技术的局限性在于，如果 HTML 表单 POST 导致请求了身份验证或重新身份验证，则浏览器发布的原始表单的内容将丢失。根据网站的功能，这可能给最终用户带来极大的不便。

mod_auth_form通过允许将原始请求的方法和主体嵌入登录表单来解决此问题。如果身份验证成功，则 Apache httpd 将重试原始方法和主体，并保留原始请求的状态。

要启用正文保存，请按照以下示例在登录表单中添加三个其他字段。

身体保护的例子

<form method="POST" action="">
  Username: <input type="text" name="httpd_username" value="" />
  Password: <input type="password" name="httpd_password" value="" />
  <input type="submit" name="login" value="Login" />
    <input type="hidden" name="httpd_method" value="POST" />
  <input type="hidden" name="httpd_mimetype" value="application/x-www-form-urlencoded" />
  <input type="hidden" name="httpd_body" value="name1=value1&name2=value2" /> 
</form>

如何将原始请求的方法，模仿类型和主体嵌入登录表单中，这取决于网站中使用的平台和技术。

一种选择是使用mod_include模块和KeptBodySize指令以及合适的 CGI 脚本一起将变量嵌入表单中。

另一种选择是使用 CGI 脚本或其他动态技术来呈现登录表单。

CGI example

AuthFormProvider file
ErrorDocument 401 "/cgi-bin/login.cgi"
...

Logging Out

为了使用户能够注销特定的会话，请配置要由 form-logout-handler 处理的页面。任何尝试访问此 URL 的操作都会导致用户名和密码从当前会话中删除，从而有效地注销用户。

通过设置AuthFormLogoutLocation伪指令，可以指定一个 URL，以便成功注销后将浏览器重定向到该 URL。该 URL 可能会向用户说明他们已经注销，并为用户提供了重新登录的选项。

基本注销示例

SetHandler form-logout-handler
AuthName realm
AuthFormLogoutLocation "http://example.com/loggedout.html"
Session On
SessionCookieName session path=/

请注意，注销用户并不会删除会话。它只是从会话中删除用户名和密码。如果这导致会话为空，则最终结果将是删除该会话，但这不能保证。如果要保证删除会话，请将SessionMaxAge伪指令设置为一个较小的值，例如 1(将伪指令设置为零将意味着没有会话期限限制)。

基本会话到期示例

SetHandler form-logout-handler
AuthFormLogoutLocation "http://example.com/loggedout.html"
Session On
SessionMaxAge 1
SessionCookieName session path=/

用户名和密码

请注意，表单提交涉及 URLEncoding 表单数据：在这种情况下，用户名和密码。因此，您应该选择避免在表单提交中使用 URL 编码的字符的用户名和密码，否则可能会得到意外的结果。

AuthFormAuthoritative Directive

Description:设置是否将授权和身份验证传递给较低级别的模块
Syntax:AuthFormAuthoritative On|Off
Default:AuthFormAuthoritative On
Context:directory, .htaccess
Override:AuthConfig
Status:Base
Module:mod_auth_form

通常，AuthFormProvider中列出的每个授权模块都将尝试验证用户，如果在任何提供程序中都找不到该用户，则将拒绝访问。将AuthFormAuthoritative指令显式设置为Off，可以在没有 用户 ID 或 规则 与提供的用户 ID 匹配的情况下将身份验证和授权传递给其他基于非提供商的模块。仅当将mod_auth_form与未使用AuthFormProvider指令配置的第三方模块结合使用时，才需要这样做。使用此类模块时，处理 Sequences 由模块的源代码确定，并且不可配置。

AuthFormBody Directive

Description:表单域的名称，其中包含尝试成功登录的请求的主体
Syntax:AuthFormBody fieldname
Default:AuthFormBody httpd_body
Context:directory
Status:Base
Module:mod_auth_form
Compatibility:在 Apache HTTP Server 2.3.0 和更高版本中可用

AuthFormBody指令指定 HTML 字段的名称(如果存在)，它将包含登录成功后提交的请求的正文。

通过使用AuthFormMethod，AuthFormMimetype和AuthFormBody描述的字段填充表单，网站可以重试可能已被登录屏幕或会话超时中断的请求。

AuthFormDisableNoStore Directive

Description:在登录页面上禁用 CacheControl 无存储头
Syntax:AuthFormDisableNoStore On|Off
Default:AuthFormDisableNoStore Off
Context:directory
Status:Base
Module:mod_auth_form
Compatibility:在 Apache HTTP Server 2.3.0 和更高版本中可用

AuthFormDisableNoStore标志禁止发送Cache-Control no-storeHeaders，并在用户尚未登录时返回错误 401 页面。Headers 的目的是使ecmascript应用程序难以尝试重新提交登录表单并显示后端应用程序的用户名和密码。禁用后果自负。

AuthFormFakeBasicAuth Directive

Description:伪造基本身份验证 Headers
Syntax:AuthFormFakeBasicAuth On|Off
Default:AuthFormFakeBasicAuth Off
Context:directory
Status:Base
Module:mod_auth_form
Compatibility:在 Apache HTTP Server 2.3.0 和更高版本中可用

AuthFormFakeBasicAuth标志确定是否将Basic AuthenticationHeaders 添加到请求 Headers。这可用于向基础应用程序公开用户名和密码，而基础应用程序不必知道如何实现登录。

AuthFormLocation Directive

Description:成功登录后带有 URL 的表单字段的名称
Syntax:AuthFormLocation fieldname
Default:AuthFormLocation httpd_location
Context:directory
Status:Base
Module:mod_auth_form
Compatibility:在 Apache HTTP Server 2.3.0 和更高版本中可用

AuthFormLocation伪指令指定 HTML 字段的名称，如果存在，则将包含一个 URL，以将浏览器重定向到登录成功的位置。

AuthFormLoginRequiredLocation Directive

Description:需要登录后要重定向到的页面的 URL
Syntax:AuthFormLoginRequiredLocation url
Default:none
Context:directory
Status:Base
Module:mod_auth_form
Compatibility:在 Apache HTTP Server 2.3.0 和更高版本中可用。在 2.4.4 中添加了表达式解析器的用法。

AuthFormLoginRequiredLocation指令指定了如果用户无权查看页面则重定向到的 URL。该值在发送给 Client 端之前，使用ap_expr解析器进行了解析。默认情况下，如果用户无权查看页面，则 HTTP 响应代码HTTP_UNAUTHORIZED将与ErrorDocument指令指定的页面一起返回。该指令将覆盖此默认值。

如果您有专用的登录页面将用户重定向到，请使用此伪指令。

AuthFormLoginSuccessLocation Directive

Description:登录成功后要重定向到的页面的 URL
Syntax:AuthFormLoginSuccessLocation url
Default:none
Context:directory
Status:Base
Module:mod_auth_form
Compatibility:在 Apache HTTP Server 2.3.0 和更高版本中可用。在 2.4.4 中添加了表达式解析器的用法。

AuthFormLoginSuccessLocation伪指令指定用户成功登录后重定向到的 URL。该值在发送给 Client 端之前，使用ap_expr解析器进行了解析。如果使用AuthFormLocation指令定义了包含另一个 URL 的表单字段，则可以覆盖此指令。

如果您有专用的登录 URL，并且尚未将目标页面嵌入登录表单，请使用此伪指令。

AuthFormLogoutLocation Directive

Description:用户注销后重定向到的 URL
Syntax:AuthFormLogoutLocation uri
Default:none
Context:directory
Status:Base
Module:mod_auth_form
Compatibility:在 Apache HTTP Server 2.3.0 和更高版本中可用。在 2.4.4 中添加了表达式解析器的用法。

AuthFormLogoutLocation伪指令指定服务器上页面的 URL，以供用户尝试注销时重定向到该页面。该值在发送给 Client 端之前，使用ap_expr解析器进行了解析。

当访问由处理程序form-logout-handler提供的 URI 时，此指令指定的页面将显示给最终用户。例如：

Example

<Location "/logout">
    SetHandler form-logout-handler
    AuthFormLogoutLocation "http://example.com/loggedout.html"
    Session on
    #...
</Location>

尝试访问 URI/logout /将导致用户被注销，并显示/loggedout.html 页面。确保页面 loginout.html 没有密码保护，否则将不会显示该页面。

AuthFormMethod Directive

Description:表单域的名称，其中包含尝试成功登录的请求方法
Syntax:AuthFormMethod fieldname
Default:AuthFormMethod httpd_method
Context:directory
Status:Base
Module:mod_auth_form
Compatibility:在 Apache HTTP Server 2.3.0 和更高版本中可用

AuthFormMethod伪指令指定 HTML 字段的名称(如果存在)，它将包含登录成功后提交请求的方法。

通过使用AuthFormMethod，AuthFormMimetype和AuthFormBody描述的字段填充表单，网站可以重试可能已被登录屏幕或会话超时中断的请求。

AuthFormMimetype Directive

Description:表单域的名称，其中包含尝试成功登录的请求主体的模仿类型
Syntax:AuthFormMimetype fieldname
Default:AuthFormMimetype httpd_mimetype
Context:directory
Status:Base
Module:mod_auth_form
Compatibility:在 Apache HTTP Server 2.3.0 和更高版本中可用

AuthFormMimetype伪指令指定 HTML 字段的名称，如果存在，它将包含登录成功后要提交的请求的模仿类型。

通过使用AuthFormMethod，AuthFormMimetype和AuthFormBody描述的字段填充表单，网站可以重试可能已被登录屏幕或会话超时中断的请求。

AuthFormPassword Directive

Description:带有登录密码的表单字段的名称
Syntax:AuthFormPassword fieldname
Default:AuthFormPassword httpd_password
Context:directory
Status:Base
Module:mod_auth_form
Compatibility:在 Apache HTTP Server 2.3.0 和更高版本中可用

AuthFormPassword伪指令指定 HTML 字段的名称，如果存在，则将包含用于登录的密码。

AuthFormProvider Directive

Description:设置此位置的身份验证提供程序
Syntax:AuthFormProvider provider-name [provider-name] ...
Default:AuthFormProvider file
Context:directory, .htaccess
Override:AuthConfig
Status:Base
Module:mod_auth_form

AuthFormProvider指令设置使用哪个提供程序来验证此位置的用户。默认的file提供程序由mod_authn_file模块实现。确保服务器中存在所选的提供程序模块。

Example

<Location "/secure">
    AuthType form
    AuthName "private area"
    AuthFormProvider  dbm
    AuthDBMType        SDBM
    AuthDBMUserFile    "/www/etc/dbmpasswd"
    Require            valid-user
    #...
</Location>

提供者由mod_authn_dbm，mod_authn_file，mod_authn_dbd，mod_authnz_ldap和mod_authn_socache实现。

AuthFormSitePassphrase Directive

Description:绕过高流量站点的身份验证检查
Syntax:AuthFormSitePassphrase secret
Default:none
Context:directory
Status:Base
Module:mod_auth_form
Compatibility:在 Apache HTTP Server 2.3.0 和更高版本中可用

AuthFormSitePassphrase伪指令指定了一个密码短语，如果该密码短语存在于用户会话中，则会使 Apache httpd 绕过针对给定 URL 的身份验证检查。它可以用于高流量的网站上，以减轻身份验证基础结构带来的负担。

通过将此指令添加到 form-login-handler 的配置中，可以将密码短语插入用户会话。表单登录处理程序本身将始终运行身份验证检查，而不管是否指定了密码短语。

Warning

如果会话是通过使用mod_session_cookie向用户公开的，并且该会话不受mod_session_crypto的保护，则密码短语可能会因字典攻击而暴露给潜在用户。无论如何配置会话，请确保不要在可能暴露私有用户数据或可以进行敏感事务的 URL 空间中使用此伪指令。使用风险自负。

AuthFormSize Directive

Description:表单的最大大小(以字节为单位)，将解析为登录详细信息
Syntax:AuthFormSize size
Default:AuthFormSize 8192
Context:directory
Status:Base
Module:mod_auth_form
Compatibility:在 Apache HTTP Server 2.3.0 和更高版本中可用

AuthFormSize指令指定将被解析以查找登录表单的请求正文的最大大小。

如果到达的登录请求超出此大小，则整个请求将被 HTTP 响应代码HTTP_REQUEST_TOO_LARGE中止。

如果您使用AuthFormMethod，AuthFormMimetype和AuthFormBody描述的字段填充表单，则可能需要将此字段设置为与KeptBodySize指令相似的大小。

AuthFormUsername Directive

Description:带有登录用户名的表单字段的名称
Syntax:AuthFormUsername fieldname
Default:AuthFormUsername httpd_username
Context:directory
Status:Base
Module:mod_auth_form
Compatibility:在 Apache HTTP Server 2.3.0 和更高版本中可用

AuthFormUsername伪指令指定 HTML 字段的名称，如果存在，则将包含用于登录的用户名。

Name Apache 中文文档
Version
Language
Badge
Last Updated 2021-07-07T12:52