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 指令所指定的網址一般會指向一個網頁，說明使用者其登入嘗試失敗，並且應再試一次。 AuthFormLoginSuccessLocation 指令會指定使用者在成功登入後應被重新導向的網址。

另外，也可以將在成功時重新導向使用者的網址內嵌在登入表單中，如下面的範例。如此一來，相同的 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=/

錯誤文件網頁應包含一個動作屬性為空的登入表單，如下面的範例所示。這會產生將表單提交至原始受保護網址的效果，而此網頁並不需要知道該網址為何。

<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 類型和主體是如何嵌入登入表單中將取決於網站內使用的平台與技術。

一種選項是搭配 KeptBodySize 指令使用 mod_include 模組，以及一個合適的 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=/

使用者名稱與密碼

請注意表單送出包括表單資料的 URLEncoding ：在本例中為使用者名稱和密碼。因此，您應選取避免在表單送出中 URL 編碼的字元作為使用者名稱和密碼，否則可能會得到意外結果。