Модуль Apache mod_auth_form

Резюме

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

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

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

Базовая конфигурация

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

Директивы Session и SessionCookieName хранят сессию в HTTP-cookie в браузере. Для получения дополнительной информации о различных вариантах конфигурации сессии, обратитесь к документации по mod_session.

Можно дополнительно добавить SessionCryptoPassphrase для создания зашифрованного куки сессии. Это требует загрузки дополнительного модуля 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>

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

Когда пользователь ввёл данные входа, форма отправит HTTP-запрос POST на исходный защищенный URL. mod_auth_form перехватит этот запрос POST, и если будут найдены поля HTML для имени пользователя и пароля, пользователь будет авторизован, и исходный защищенный URL будет возвращён пользователю в виде запроса GET.

Встроенный вход с сохранением содержимого тела

Ограничением техники встроенного входа, описанной выше, является то, что в случае, если POST-запрос HTML-формы привел к запросу на аутентификацию или повторную аутентификацию, содержимое исходной формы, отправленной браузером, будет потеряно. В зависимости от функции веб-сайта это может доставить значительные неудобства пользователю.

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 может объяснить пользователю, что он вышел из системы, и предоставить возможность повторного входа.

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

Обратите внимание, что выход из системы не удаляет сессию; он просто удаляет имя пользователя и пароль из сессии. Если это приводит к пустой сессии, то в итоге будет удалена эта сессия, но это не гарантируется. Если вы хотите гарантировать удаление сессии, установите директиву SessionMaxAge на малое значение, например, 1 (установка значения 0 означала бы отсутствие ограничения возраста сессии).

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