mod_auth_form

摘要

警告

表单身份验证取决于mod_session模块，并且这些模块使用 HTTP cookies，因此可能成为 Cross Site Scripting 攻击的受害者，或者可能将私有信息暴露给 clients。在服务器上启用 session 功能之前，请确保已考虑相关风险。

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

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

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

基本 Configuration

要使用mod_auth_form保护特定 URL，您需要决定将 session 存储在哪里，并且您需要决定使用哪种方法进行身份验证。在这个简单的 example 中，登录详细信息将存储在基于mod_sessioncookie的 session 中，并且将使用mod_authn_file对文件进行身份验证。如果身份验证不成功，用户将被重定向到表单登录页面。

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

当设置为 value 表单时，指令进行 AuthType将启用mod_auth_form身份验证。指令AuthFormProvider和AuthUserFile指定应根据所选文件检查用户名和密码。

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

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

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

独立登录

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

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

Example 登录表单

<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 中配置如下：

表单登录处理程序 example

<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 嵌入到登录表单中，如下面的 example 中所示。因此，相同的 form-login-handler 可以重复用于网站的不同区域。

Example 带位置的登录表单

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

内联登录

警告

存在这样的风险：在某些情况下，使用内联登录配置的登录表单可能会被多次提交，从而向下面的 application running 显示登录凭据。管理员必须确保正确保护基础应用程序以防止滥用。如有疑问，请使用独立登录 configuration。

作为具有网站专用登录页面的替代方案，可以配置mod_auth_form以内联对用户进行身份验证，而不会被重定向到另一个页面。这允许在登录尝试期间保留当前页面的 state。这在 time 限制 session 有效且 session 在用户请求中间超时的情况下非常有用。用户可以 re-authenticated 到位，他们可以继续他们离开的地方。

如果 non-authenticated 用户尝试访问受mod_auth_form保护且未配置AuthFormLoginRequiredLocation指令的页面，则会向浏览器返回 HTTP_UNAUTHORIZED status code，向用户表明他们无权查看该页面。

要配置内联身份验证，管理员会使用包含登录表单的自定义错误文档覆盖 HTTP_UNAUTHORIZED status code 返回的错误文档，如下所示：

基本内联 example

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

错误文档页面应包含一个空操作 property 的登录表单，如下面的 example 所示。这具有将表单提交到原始受保护 URL 的效果，而页面不必知道该 URL 是什么。

Example 内联登录表单

<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 将重试原始方法和正文，同时保留原始请求的 state。

要启用正文保存，请根据下面的 example 向登录表单添加三个附加字段。

例如身体保存

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

如何在登录表单中嵌入原始请求的方法，mimetype 和正文将取决于网站中使用的平台和技术。

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

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

CGI example

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

退出

要使用户能够 log 退出特定的 session，请配置要由 form-logout-handler 处理的页面。任何访问此 URL 的尝试都将导致从当前 session 中删除用户名和密码，从而有效 logging 用户。

通过设置AuthFormLogoutLocation指令，可以指定一个 URL，以便在成功注销时将浏览器重定向到。此 URL 可能会向用户解释他们已注销，并再次向用户提供 log 选项。

基本注销 example

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

注意 logging 用户输出不会删除 session;它只是从 session 中删除了用户名和密码。如果这导致空 session，则净效果将是删除该 session，但这不能保证。如果要保证删除 session，请将SessionMaxAge指令设置为小 value，例如 1(将指令设置为零意味着没有 session 年龄限制)。

基本 session expiry example

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

用户名和密码

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

AuthFormAuthoritative Directive

通常，AuthFormProvider中列出的每个授权模块都将尝试验证用户，如果在任何提供程序中找不到该用户，则访问将被拒绝。将AuthFormAuthoritative指令显式设置为Off允许将身份验证和授权传递给其他 non-provider-based 模块，如果没有与提供的 userID 匹配的 userID或规则。只有在将mod_auth_form与未使用AuthFormProvider指令配置的 third-party 模块组合时才需要这样做。使用此类模块时，处理的 order 在模块的 source code 中确定，并且不可配置。

AuthFormBody 指令

AuthFormMethod指令指定 HTML 字段的 name，如果存在，将包含登录成功时要提交的请求的方法。

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

AuthFormDisableNoStore 指令

AuthFormDisableNoStore flag 禁用发送Cache-Control no-store标头，并在用户尚未登录时返回错误 401 页面。标题的目的是使ecmascript application 难以重新提交登录表单，并显示后端 application 的用户名和密码。禁用，风险自负。

AuthFormFakeBasicAuth 指令

AuthFormFakeBasicAuth flag 确定是否将Basic Authentication标头添加到请求 headers。这可用于将用户名和密码公开给底层的 application，而底层的 application 不必知道登录是如何实现的。

AuthFormLocation 指令

AuthFormLocation指令指定 HTML 字段的 name，如果存在，则该字段将包含一个 URL，以便在登录成功时将浏览器重定向到该 URL。

AuthFormLoginRequiredLocation 指令

如果用户无权查看页面，则AuthFormLoginRequiredLocation指令指定要重定向到的 URL。在发送到 client 之前，使用ap_expr解析器解析 value。默认情况下，如果用户无权查看页面，则将返回 HTTP 响应 code HTTP_UNAUTHORIZED以及ErrorDocument指令指定的页面。该指令覆盖此默认值。

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

AuthFormLoginSuccessLocation 指令

如果用户已成功登录，则AuthFormLoginSuccessLocation指令指定要重定向到的 URL。在发送到 client 之前，使用ap_expr解析器解析 value。如果已使用AuthFormLocation指令定义了包含其他 URL 的表单字段，则可以覆盖此指令。

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

AuthFormLogoutLocation 指令

如果用户尝试 log，则AuthFormLogoutLocation指令指定要重定向到的服务器上的页面的 URL。在发送到 client 之前，使用ap_expr解析器解析 value。

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

例

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

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

AuthFormMethod 指令

AuthFormMethod指令指定 HTML 字段的 name，如果存在，将包含登录成功时要提交的请求的方法。

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

AuthFormMimetype 指令

AuthFormMethod指令指定 HTML 字段的 name，如果存在，将包含登录成功时要提交的请求的 mimetype。

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

AuthFormPassword 指令

AuthFormPassword指令指定 HTML 字段的 name，如果存在，将包含用于 log 的密码。

AuthFormProvider 指令

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

例

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

AuthFormSitePassphrase指令指定一个密码短语，如果存在于用户 session 中，则会导致 Apache httpd 绕过给定 URL 的身份验证检查。它可以在高流量网站上使用，以减少在身份验证基础架构上引起的负载。

通过将此指令添加到 form-login-handler 的 configuration，可以将密码插入到用户 session 中。无论是否指定了密码，form-login-handler 本身都将始终运行身份验证检查。

警告

如果 session 通过使用mod_sessioncookie向用户公开，并且 session 不受mod_sessioncrypto保护，则密码短语可能会通过字典攻击进行潜在曝光。无论如何配置 session，请确保在可以公开私有用户数据的 URL 空间中不使用此指令，或者可以执行敏感的 transactions。使用风险自负。

AuthFormSize 指令

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

如果登录请求超过此大小，则整个请求将使用 HTTP 响应 code HTTP_REQUEST_TOO_LARGE中止。

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

AuthFormUsername 指令

AuthFormUsername指令指定 HTML 字段的 name，如果存在，将包含用于 log 的用户名。