Apache 模块 mod_auth_form

基本配置

要使用 mod_auth_form 保护特定 URL，您需要决定将 session 存储在何处，以及将使用什么方法进行身份验证。在此简单示例中，登录详细信息将存储在基于 mod_session_cookie 的会话中，并且将使用 mod_authn_file 对文件进行身份验证。如果身份验证失败，用户将被重定向到表单登录页面。

<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 将在设置为 form 值时启用 mod_auth_form 身份验证。指令 AuthFormProvider 和 AuthUserFile 指定应针对所选文件检查用户名和密码。

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

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

在上面的简单示例中，一个 URL 已被 mod_auth_form 保护，但用户尚未获得输入用户名和密码的机会。为此目的，可以选择提供一个专用的独立登录页面，或在同一页面上提供内联登录页面。

独立登录

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

在将登录配置为独立页面时，应使用 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-login-handler 可用于网站的不同区域。

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

内联登录

作为为网站提供专用登录页面的替代方案，可以配置 mod_auth_form 以内联方式验证用户，而无需重定向到另一个页面。这允许在登录尝试期间保留当前页面的状态。这在强制执行时间限制会话且会话在用户请求中途超时的情况下很有用。用户可以在原地重新验证，并从他们离开的地方继续操作。

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

要配置内联身份验证，管理员会使用包含登录表单的自定义错误文档覆盖由 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=/

错误文档页面应包含一个具有空操作属性的登录表单，如下例所示。这将使表单提交到原始受保护的 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>

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

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

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

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

注销

要使用户能够注销特定会话，请配置一个由 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=/

用户名和密码

请注意，表单提交涉及对表单数据进行 URL 编码：在本例中为用户名和密码。因此，您应该选择不会在表单提交中进行 URL 编码的用户名和密码，否则您可能会得到意外的结果。