Модуль Apache mod_auth_form

Краткое описание

Этот модуль позволяет использовать HTML-форму входа для ограничения доступа, проверяя пользователей в указанных поставщиках. HTML-формы требуют значительно более сложной настройки, чем альтернативные варианты, однако HTML-форма входа может обеспечить гораздо более удобное взаимодействие для конечных пользователей.

Базовая аутентификация HTTP предоставляется модулем mod_auth_basic, а дайджест-аутентификация HTTP — модулем mod_auth_digest. Этот модуль следует использовать вместе как минимум с одним модулем аутентификации, например mod_authn_file, и одним модулем авторизации, например mod_authz_user.

После успешной аутентификации пользователя его учетные данные для входа будут сохранены в сеансе, предоставляемом модулем mod_session.

Базовая настройка

Чтобы защитить определенный URL с помощью mod_auth_form, необходимо решить, где будет храниться ваш сеанс, а также выбрать способ аутентификации. В этом простом примере учетные данные для входа будут храниться в сеансе на основе 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 включает аутентификацию mod_auth_form, если ей задано значение form. Директивы AuthFormProvider и AuthUserFile указывают, что имена пользователей и пароли следует проверять по выбранному файлу.

Директивы Session и SessionCookieName задают хранение сеанса в файле cookie HTTP в браузере. Дополнительные сведения о различных вариантах настройки сеанса см. в документации к 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. В атрибуте action формы следует указать этот обработчик, который настраивается в 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>

URL, указанные директивой AuthFormLoginRequiredLocation, обычно ведут на страницу с сообщением о неудачной попытке входа и предложением повторить попытку. Директива 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
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>

Когда конечный пользователь введет свои учетные данные, форма отправит запрос HTTP POST на исходный URL, защищенный паролем. 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, на который браузер будет перенаправлен после успешного выхода. На этой странице можно сообщить пользователю, что он вышел из системы, и предложить ему войти снова.

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 при отправке формы, иначе возможны непредвиденные результаты.

AuthFormAuthoritative On|Off

AuthFormAuthoritative On

AuthFormBody fieldname

AuthFormBody httpd_body

AuthFormDisableNoStore On|Off

AuthFormDisableNoStore Off

AuthFormFakeBasicAuth On|Off

AuthFormFakeBasicAuth Off

AuthFormLocation fieldname

AuthFormLocation httpd_location

AuthFormLoginRequiredLocation url

AuthFormLoginSuccessLocation url

AuthFormLogoutLocation uri

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

AuthFormMethod fieldname

AuthFormMethod httpd_method

AuthFormMimetype fieldname

AuthFormMimetype httpd_mimetype

AuthFormPassword fieldname

AuthFormPassword httpd_password

AuthFormProvider provider-name [provider-name] ...

AuthFormProvider file

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

AuthFormSitePassphrase secret

AuthFormSize size

AuthFormSize 8192

AuthFormUsername fieldname

AuthFormUsername httpd_username