88ae7333ee052e64607ae6678fe0e84991fe3482Zbigniew Jędrzejewski-Szmek<?xml version="1.0"?>

88ae7333ee052e64607ae6678fe0e84991fe3482Zbigniew Jędrzejewski-Szmek<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">

12b42c76672a66c2d4ea7212c14f8f1b5a62b78dTom Gundersen<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>

88ae7333ee052e64607ae6678fe0e84991fe3482Zbigniew Jędrzejewski-Szmek

88ae7333ee052e64607ae6678fe0e84991fe3482Zbigniew Jędrzejewski-Szmek

4f50d2efbac87aba0505b9f998bf3e4bde64c214Zbigniew Jędrzejewski-Szmek<modulesynopsis metafile="mod_auth_form.xml.meta">

4f50d2efbac87aba0505b9f998bf3e4bde64c214Zbigniew Jędrzejewski-Szmek

4f50d2efbac87aba0505b9f998bf3e4bde64c214Zbigniew Jędrzejewski-Szmek<name>mod_auth_form</name>

4f50d2efbac87aba0505b9f998bf3e4bde64c214Zbigniew Jędrzejewski-Szmek<description>Form authentication</description>

4f50d2efbac87aba0505b9f998bf3e4bde64c214Zbigniew Jędrzejewski-Szmek<status>Base</status>

4f50d2efbac87aba0505b9f998bf3e4bde64c214Zbigniew Jędrzejewski-Szmek<sourcefile>mod_auth_form.c</sourcefile>

db6d9e864083b3ce8206a065e9edaa5fd19bab39Lennart Poettering<identifier>auth_form_module</identifier>

4f50d2efbac87aba0505b9f998bf3e4bde64c214Zbigniew Jędrzejewski-Szmek

db6d9e864083b3ce8206a065e9edaa5fd19bab39Lennart Poettering<summary>

db6d9e864083b3ce8206a065e9edaa5fd19bab39Lennart Poettering <note type="warning"><title>Warning</title>

db6d9e864083b3ce8206a065e9edaa5fd19bab39Lennart Poettering <p>Form authentication depends on the <module>mod_session</module>

db6d9e864083b3ce8206a065e9edaa5fd19bab39Lennart Poettering modules, and these modules make use of HTTP cookies, and as such can fall

db6d9e864083b3ce8206a065e9edaa5fd19bab39Lennart Poettering victim to Cross Site Scripting attacks, or expose potentially private

db6d9e864083b3ce8206a065e9edaa5fd19bab39Lennart Poettering information to clients. Please ensure that the relevant risks have

db6d9e864083b3ce8206a065e9edaa5fd19bab39Lennart Poettering been taken into account before enabling the session functionality on

4f50d2efbac87aba0505b9f998bf3e4bde64c214Zbigniew Jędrzejewski-Szmek your server.</p>

4f50d2efbac87aba0505b9f998bf3e4bde64c214Zbigniew Jędrzejewski-Szmek </note>

4f50d2efbac87aba0505b9f998bf3e4bde64c214Zbigniew Jędrzejewski-Szmek

4f50d2efbac87aba0505b9f998bf3e4bde64c214Zbigniew Jędrzejewski-Szmek <p>This module allows the use of an HTML login form to restrict access

4f50d2efbac87aba0505b9f998bf3e4bde64c214Zbigniew Jędrzejewski-Szmek by looking up users in the given providers. HTML forms require

4f50d2efbac87aba0505b9f998bf3e4bde64c214Zbigniew Jędrzejewski-Szmek significantly more configuration than the alternatives, however an

4f50d2efbac87aba0505b9f998bf3e4bde64c214Zbigniew Jędrzejewski-Szmek HTML login form can provide a much friendlier experience for end users.

4f50d2efbac87aba0505b9f998bf3e4bde64c214Zbigniew Jędrzejewski-Szmek </p>

4f50d2efbac87aba0505b9f998bf3e4bde64c214Zbigniew Jędrzejewski-Szmek

4f50d2efbac87aba0505b9f998bf3e4bde64c214Zbigniew Jędrzejewski-Szmek <p>HTTP basic authentication is provided by

4f50d2efbac87aba0505b9f998bf3e4bde64c214Zbigniew Jędrzejewski-Szmek <module>mod_auth_basic</module>, and HTTP digest authentication is

4f50d2efbac87aba0505b9f998bf3e4bde64c214Zbigniew Jędrzejewski-Szmek provided by <module>mod_auth_digest</module>. This module should

88ae7333ee052e64607ae6678fe0e84991fe3482Zbigniew Jędrzejewski-Szmek be combined with at least one authentication module

such as <module>mod_authn_file</module> and one authorization

module such as <module>mod_authz_user</module>.</p>

<p>Once the user has been successfully authenticated, the user's login

details will be stored in a session provided by <module>mod_session</module>.

</p>

</summary>

<seealso><module>mod_session</module></seealso>

<seealso><directive module="mod_authn_core">AuthName</directive></seealso>

<seealso><directive module="mod_authn_core">AuthType</directive></seealso>

<seealso><directive module="mod_authz_core">Require</directive></seealso>

<seealso><directive module="mod_authz_core">Match</directive></seealso>

<seealso><a href="/howto/auth.html">Authentication howto</a></seealso>

<section id="basicconfig"><title>Basic Configuration</title>

<p>To protect a particular URL with <module>mod_auth_form</module>, you need to

decide where you will store your <var>session</var>, and you will need to

decide what method you will use to authenticate. In this simple example, the

login details will be stored in a session based on

<module>mod_session_cookie</module>, and authentication will be attempted against

a file using <module>mod_authn_file</module>. If authentication is unsuccessful,

the user will be redirected to the form login page.</p>

<example><title>Basic example</title>

AuthFormProvider file<br />

AuthUserFile conf/passwd<br />

AuthType form<br />

AuthName realm<br />

AuthFormLoginRequiredLocation http://example.com/login.html<br />

Session On<br />

SessionCookieName session path=/<br />

SessionCryptoPassphrase secret<br />

</example>

<p>The directive <directive module="mod_authn_core">AuthType</directive> will enable

the <module>mod_auth_form</module> authentication when set to the value <var>form</var>.

The directives <directive module="mod_auth_form">AuthFormProvider</directive> and

<directive module="mod_authn_file">AuthUserFile</directive> specify that usernames

and passwords should be checked against the chosen file.</p>

<p>The directives <directive module="mod_session">Session</directive>,

<directive module="mod_session_cookie">SessionCookieName</directive> and

<directive module="mod_session_crypto">SessionCryptoPassphrase</directive> create an

encrypted session stored within an HTTP cookie on the browser. For more information

on the different options for configuring a session, read the documentation for

<module>mod_session</module>.</p>

<p>In the simple example above, a URL has been protected by

<module>mod_auth_form</module>, but the user has yet to be given an opportunity to

enter their username and password. Options for doing so include providing a

dedicated standalone login page for this purpose, or for providing the login

page inline.</p>

</section>

<section id="standalone"><title>Standalone Login</title>

<p>The login form can be hosted as a standalone page, or can be provided inline on

the same page.</p>

<p>When configuring the login as a standalone page, unsuccessful authentication

attempts should be redirected to a login form created by the website for this purpose,

using the <directive module="mod_auth_form">AuthFormLoginRequiredLocation</directive>

directive. Typically this login page will contain an HTML form, asking the user to

provide their usename and password.</p>

<example><title>Example login form</title>

&lt;form method="POST" action="/dologin.html"&gt;<br />

Username: &lt;input type="text" name="httpd_username" value="" /&gt;<br />

Password: &lt;input type="password" name="httpd_password" value="" /&gt;<br />

&lt;input type="submit" name="login" value="Login" /&gt;<br />

&lt;/form&gt;<br />

</example>

<p>The part that does the actual login is handled by the <var>form-login-handler</var>.

The action of the form should point at this handler, which is configured within

Apache as follows:</p>

<example><title>Form login handler example</title>

&lt;Location /dologin.html&gt;

<indent>

SetHandler form-login-handler<br />

AuthFormLoginRequiredLocation http://example.com/login.html<br />

AuthFormLoginSuccessLocation http://example.com/success.html<br />

AuthFormProvider file<br />

AuthUserFile conf/passwd<br />

AuthType form<br />

AuthName realm<br />

Session On<br />

SessionCookieName session path=/<br />

SessionCryptoPassphrase secret<br />

</indent>

&lt;/Location&gt;

</example>

<p>The URLs specified by the

<directive module="mod_auth_form">AuthFormLoginRequiredLocation</directive> directive will typically

point to a page explaining to the user that their login attempt was unsuccessful, and they

should try again. The <directive module="mod_auth_form">AuthFormLoginSuccessLocation</directive>

directive specifies the URL the user should be redirected to upon successful login.</p>

<p>Alternatively, the URL to redirect the user to on success can be embedded within the login

form, as in the example below. As a result, the same <var>form-login-handler</var> can be

reused for different areas of a website.</p>

<example><title>Example login form with location</title>

&lt;form method="POST" action="/dologin.html"&gt;<br />

<indent>

Username: &lt;input type="text" name="httpd_username" value="" /&gt;<br />

Password: &lt;input type="password" name="httpd_password" value="" /&gt;<br />

&lt;input type="submit" name="login" value="Login" /&gt;<br />

&lt;input type="hidden" name="httpd_location" value="http://example.com/success.html" /&gt;<br />

</indent>

&lt;/form&gt;<br />

</example>

</section>

<section id="inline"><title>Inline Login</title>

<note type="warning"><title>Warning</title>

<p>A risk exists that under certain circumstances, the login form configured

using inline login may be submitted more than once, revealing login credentials to

the application running underneath. The administrator must ensure that the underlying

application is properly secured to prevent abuse. If in doubt, use the

standalone login configuration.</p>

</note>

<p>As an alternative to having a dedicated login page for a website, it is possible to

configure <module>mod_auth_form</module> to authenticate users inline, without being

redirected to another page. This allows the state of the current page to be preserved

during the login attempt. This can be useful in a situation where a time limited

session is in force, and the session times out in the middle of the user request. The

user can be re-authenticated in place, and they can continue where they left off.</p>

<p>If a non-authenticated user attempts to access a page protected by

<module>mod_auth_form</module> that isn't configured with a

<directive module="mod_auth_form">AuthFormLoginRequiredLocation</directive> directive,

a <var>HTTP_UNAUTHORIZED</var> status code is returned to the browser indicating to the user

that they are not authorized to view the page.</p>

<p>To configure inline authentication, the administrator overrides the error document

returned by the <var>HTTP_UNAUTHORIZED</var> status code with a custom error document

containing the login form, as follows:</p>

<example><title>Basic inline example</title>

AuthFormProvider file<br />

<strong>ErrorDocument 401 /login.shtml</strong><br />

AuthUserFile conf/passwd<br />

AuthType form<br />

AuthName realm<br />

AuthFormLoginRequiredLocation http://example.com/login.html<br />

Session On<br />

SessionCookieName session path=/<br />

SessionCryptoPassphrase secret<br />

</example>

<p>The error document page should contain a login form with an empty action property,

as per the example below. This has the effect of submitting the form to

the original protected URL, without the page having to know what that

URL is.</p>

<example><title>Example inline login form</title>

&lt;form method="POST" <strong>action=""</strong>&gt;<br />

<indent>

Username: &lt;input type="text" name="httpd_username" value="" /&gt;<br />

Password: &lt;input type="password" name="httpd_password" value="" /&gt;<br />

&lt;input type="submit" name="login" value="Login" /&gt;<br />

</indent>

&lt;/form&gt;<br />

</example>

<p>When the end user has filled in their login details, the form will make

an HTTP POST request to the original password protected URL.

<module>mod_auth_form</module> will intercept this POST request, and if

HTML fields are found present for the username and password, the user

will be logged in, and the original password protected URL will be returned

to the user as a GET request.</p>

</section>

<section id="inlinepreservebody"><title>Inline Login with Body Preservation</title>

<p>A limitation of the inline login technique described above is that should an

HTML form POST have resulted in the request to authenticate or reauthentiate, the

contents of the original form posted by the browser will be lost. Depending on

the function of the website, this could present significant inconvenience for the

end user.</p>

<p><module>mod_auth_form</module> addresses this by allowing the method and body

of the original request to be embedded in the login form. If authentication

is successful, the original method and body will be retried by Apache, preserving

the state of the original request.</p>

<p>To enable body preservation, add three additional fields to the login form as

per the example below.</p>

<example><title>Example with body preservation</title>

&lt;form method="POST" action=""&gt;<br />

<indent>

Username: &lt;input type="text" name="httpd_username" value="" /&gt;<br />

Password: &lt;input type="password" name="httpd_password" value="" /&gt;<br />

&lt;input type="submit" name="login" value="Login" /&gt;<br />

<strong>&lt;input type="hidden" name="httpd_method" value="POST" /&gt;<br />

&lt;input type="hidden" name="httpd_mimetype" value="application/x-www-form-urlencoded" /&gt;<br />

&lt;input type="hidden" name="httpd_body" value="name1=value1&amp;name2=value2" /&gt;</strong><br />

</indent>

&lt;/form&gt;

</example>

<p>How the method, mimetype and body of the original request are embedded within the

login form will depend on the platform and technology being used within the website.

</p>

<p>One option is to use the <module>mod_include</module> module along with the

<directive module="core">KeptBodySize</directive> directive, along with a suitable

CGI script to embed the variables in the form.</p>

<p>Another option is to render the login form using a CGI script or other dynamic

technology.</p>

<example><title>CGI example</title>

AuthFormProvider file<br />

<strong>ErrorDocument 401 /cgi-bin/login.cgi</strong><br />

...<br />

</example>

</section>

<section id="loggingout"><title>Logging Out</title>

<p>To enable a user to log out of a particular session, configure a page to

be handled by the <var>form-logout-handler</var>. Any attempt to access this

URL will cause the username and password to be removed from the current

session, effectively logging the user out.</p>

<p>By setting the

<directive module="mod_auth_form">AuthFormLogoutLocation</directive> directive,

a URL can be specified that the browser will be redirected to on successful

logout. This URL might explain to the user that they have been logged out, and

give the user the option to log in again.</p>

<example><title>Basic logout example</title>

SetHandler form-logout-handler<br />

AuthName realm<br />

AuthFormLogoutLocation http://example.com/loggedout.html<br />

Session On<br />

SessionCookieName session path=/<br />

SessionCryptoPassphrase secret<br />

</example>

<p>Note that logging a user out does not delete the session; it merely removes

the username and password from the session. If this results in an empty session,

the net effect will be the removal of that session, but this is not

guaranteed. If you want to guarantee the removal of a session, set the

<directive module="mod_session">SessionMaxAge</directive> directive to a small

value, like 1 (setting the directive to zero would mean no session age limit).

</p>

<example><title>Basic session expiry example</title>

SetHandler form-logout-handler<br />

AuthFormLogoutLocation http://example.com/loggedout.html<br />

Session On<br />

SessionMaxAge 1<br />

SessionCookieName session path=/<br />

SessionCryptoPassphrase secret<br />

</example>

</section>

<directivesynopsis>

<name>AuthFormProvider</name>

<description>Sets the authentication provider(s) for this location</description>

<syntax>AuthFormProvider <var>provider-name</var>

[<var>provider-name</var>] ...</syntax>

<default>AuthFormProvider file</default>

<contextlist><context>directory</context><context>.htaccess</context>

</contextlist>

<override>AuthConfig</override>

<usage>

<p>The <directive>AuthFormProvider</directive> directive sets

which provider is used to authenticate the users for this location.

The default <code>file</code> provider is implemented

by the <module>mod_authn_file</module> module. Make sure

that the chosen provider module is present in the server.</p>

<example><title>Example</title>

&lt;Location /secure&gt;<br />

<indent>

AuthType form<br />

AuthName "private area"<br />

AuthFormProvider dbm<br />

AuthDBMType SDBM<br />

AuthDBMUserFile /www/etc/dbmpasswd<br />

Require valid-user<br />

...<br />

</indent>

&lt;/Location&gt;

</example>

<p>Providers are implemented by <module>mod_authn_dbm</module>,

<module>mod_authn_file</module>, <module>mod_authn_dbd</module>,

and <module>mod_authnz_ldap</module>.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>AuthFormAuthoritative</name>

<description>Sets whether authorization and authentication are passed to

lower level modules</description>

<syntax>AuthFormAuthoritative On|Off</syntax>

<default>AuthFormAuthoritative On</default>

<contextlist><context>directory</context><context>.htaccess</context>

</contextlist>

<override>AuthConfig</override>

<usage>

<p>Normally, each authorization module listed in <directive

module="mod_auth_form">AuthFormProvider</directive> will attempt

to verify the user, and if the user is not found in any provider,

access will be denied. Setting the

<directive>AuthFormAuthoritative</directive> directive explicitly

to <code>Off</code> allows for both authentication and

authorization to be passed on to other non-provider-based modules

if there is <strong>no userID</strong> or <strong>rule</strong>

matching the supplied userID. This should only be necessary when

combining <module>mod_auth_form</module> with third-party modules

that are not configured with the <directive

module="mod_auth_form">AuthFormProvider</directive>

directive. When using such modules, the order of processing

is determined in the modules' source code and is not configurable.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>AuthFormUsername</name>

<description>The name of a form field carrying the login username</description>

<syntax>AuthFormUsername <var>fieldname</var></syntax>

<default>httpd_username</default>

<contextlist><context>directory</context>

</contextlist>

<compatibility>Available in Apache 2.3.0 and later</compatibility>

<usage>

<p>The <directive module="mod_auth_form">AuthFormUsername</directive> directive specifies

the name of an HTML field which, if present, will contain the username to be used to log

in.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>AuthFormPassword</name>

<description>The name of a form field carrying the login password</description>

<syntax>AuthFormPassword <var>fieldname</var></syntax>

<default>httpd_password</default>

<contextlist><context>directory</context>

</contextlist>

<compatibility>Available in Apache 2.3.0 and later</compatibility>

<usage>

<p>The <directive module="mod_auth_form">AuthFormPassword</directive> directive specifies

the name of an HTML field which, if present, will contain the password to be used to log

in.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>AuthFormLocation</name>

<description>The name of a form field carrying a URL to redirect to on successful login</description>

<syntax>AuthFormLocation <var>fieldname</var></syntax>

<default>httpd_location</default>

<contextlist><context>directory</context>

</contextlist>

<compatibility>Available in Apache 2.3.0 and later</compatibility>

<usage>

<p>The <directive module="mod_auth_form">AuthFormLocation</directive> directive specifies

the name of an HTML field which, if present, will contain a URL to redirect the browser to

should login be successful.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>AuthFormMethod</name>

<description>The name of a form field carrying the method of the request to attempt on successful login</description>

<syntax>AuthFormMethod <var>fieldname</var></syntax>

<default>httpd_method</default>

<contextlist><context>directory</context>

</contextlist>

<compatibility>Available in Apache 2.3.0 and later</compatibility>

<usage>

<p>The <directive module="mod_auth_form">AuthFormMethod</directive> directive specifies

the name of an HTML field which, if present, will contain the method of the request to

to submit should login be successful.</p>

<p>By populating the form with fields described by

<directive module="mod_auth_form">AuthFormMethod</directive>,

<directive module="mod_auth_form">AuthFormMimetype</directive> and

<directive module="mod_auth_form">AuthFormBody</directive>, a website can retry

a request that may have been interrupted by the login screen, or by a session

timeout.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>AuthFormMimetype</name>

<description>The name of a form field carrying the mimetype of the body of the request to attempt on successful login</description>

<syntax>AuthFormMimetype <var>fieldname</var></syntax>

<default>httpd_mimetype</default>

<contextlist><context>directory</context>

</contextlist>

<compatibility>Available in Apache 2.3.0 and later</compatibility>

<usage>

<p>The <directive module="mod_auth_form">AuthFormMethod</directive> directive specifies

the name of an HTML field which, if present, will contain the method of the request to

to submit should login be successful.</p>

<p>By populating the form with fields described by

<directive module="mod_auth_form">AuthFormMethod</directive>,

<directive module="mod_auth_form">AuthFormMimetype</directive> and

<directive module="mod_auth_form">AuthFormBody</directive>, a website can retry

a request that may have been interrupted by the login screen, or by a session

timeout.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>AuthFormBody</name>

<description>The name of a form field carrying the body of the request to attempt on successful login</description>

<syntax>AuthFormBody <var>fieldname</var></syntax>

<default>httpd_body</default>

<contextlist><context>directory</context>

</contextlist>

<compatibility>Available in Apache 2.3.0 and later</compatibility>

<usage>

<p>The <directive module="mod_auth_form">AuthFormMethod</directive> directive specifies

the name of an HTML field which, if present, will contain the method of the request to

to submit should login be successful.</p>

<p>By populating the form with fields described by

<directive module="mod_auth_form">AuthFormMethod</directive>,

<directive module="mod_auth_form">AuthFormMimetype</directive> and

<directive module="mod_auth_form">AuthFormBody</directive>, a website can retry

a request that may have been interrupted by the login screen, or by a session

timeout.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>AuthFormSize</name>

<description>The largest size of the form in bytes that will be parsed for the login details</description>

<syntax>AuthFormBody <var>size</var></syntax>

<default>8192</default>

<contextlist><context>directory</context>

</contextlist>

<compatibility>Available in Apache 2.3.0 and later</compatibility>

<usage>

<p>The <directive module="mod_auth_form">AuthFormSize</directive> directive specifies

the maximum size of the body of the request that will be parsed to find the login form.</p>

<p>If a login request arrives that exceeds this size, the whole request will be aborted

with the HTTP response code <code>HTTP_REQUEST_TOO_LARGE</code>.</p>

<p>If you have populated the form with fields described by

<directive module="mod_auth_form">AuthFormMethod</directive>,

<directive module="mod_auth_form">AuthFormMimetype</directive> and

<directive module="mod_auth_form">AuthFormBody</directive>, you probably want to set this

field to a similar size as the <directive module="core">KeptBodySize</directive>

directive.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>AuthFormLoginRequiredLocation</name>

<description>The URL of the page to be redirected to should login be required</description>

<syntax>AuthFormLoginRequiredLocation <var>url</var></syntax>

<default>none</default>

<contextlist><context>directory</context>

</contextlist>

<compatibility>Available in Apache 2.3.0 and later</compatibility>

<usage>

<p>The <directive module="mod_auth_form">AuthFormLoginRequiredLocation</directive> directive

specifies the URL to redirect to should the user not be authorised to view a page. By default,

if a user is not authorised to view a page, the HTTP response code <code>HTTP_UNAUTHORIZED</code>

will be returned with the page specified by the

<directive module="mod_core">ErrorDocument</directive> directive. This directive overrides this

default.</p>

<p>Use this directive if you have a dedicated login page to redirect users to.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>AuthFormLoginSuccessLocation</name>

<description>The URL of the page to be redirected to should login be successful</description>

<syntax>AuthFormLoginSuccessLocation <var>url</var></syntax>

<default>none</default>

<contextlist><context>directory</context>

</contextlist>

<compatibility>Available in Apache 2.3.0 and later</compatibility>

<usage>

<p>The <directive module="mod_auth_form">AuthFormLoginSuccessLocation</directive> directive

specifies the URL to redirect to should the user have logged in successfully. This directive

can be overridden if a form field has been defined containing another URL using the

<directive module="mod_auth_form">AuthFormLocation</directive> directive.</p>

<p>Use this directive if you have a dedicated login URL, and you have not embedded the

destination page in the login form.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>AuthFormFakeBasicAuth</name>

<description>Fake a Basic Authentication header</description>

<syntax>AuthFormFakeBasicAuth <var>On|Off</var></syntax>

<default>AuthFormFakeBasicAuth Off</default>

<contextlist><context>directory</context>

</contextlist>

<compatibility>Available in Apache 2.3.0 and later</compatibility>

<usage>

<p>The <directive module="mod_auth_form">AuthFormFakeBasicAuth</directive> flag

determines whether a <code>Basic Authentication</code> header will be added to

the request headers. This can be used to expose the username and password to

an underlying application, without the underlying application having to be aware

of how the login was achieved.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>AuthFormLogoutLocation</name>

<description>The URL to redirect to after a user has logged out</description>

<syntax>AuthFormLogoutLocation <var>uri</var></syntax>

<default>none</default>

<contextlist><context>directory</context>

</contextlist>

<compatibility>Available in Apache 2.3.0 and later</compatibility>

<usage>

<p>The <directive module="mod_auth_form">AuthFormLogoutLocation</directive> directive

specifies the URL of a page on the server to redirect to should the user attempt to log out.</p>

<p>When a URI is accessed that is served by the handler <code>form-logout-handler</code>,

the page specified by this directive will be shown to the end user. For example:</p>

<example><title>Example</title>

&lt;Location /logout&gt;<br />

<indent>

SetHandler form-logout-handler<br />

AuthFormLogoutLocation http://example.com/loggedout.html<br />

Session on<br />

...

</indent>

&lt;/Location&gt;

</example>

<p>An attempt to access the URI <var>/logout/</var> will result in the user being logged

out, and the page <var>/loggedout.html</var> will be displayed. Make sure that the page

<var>loggedout.html</var> is not password protected, otherwise the page will not be

displayed.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>AuthFormDisableNoStore</name>

<description>Disable the CacheControl no-store header on the login page</description>

<syntax>AuthFormDisableNoStore <var>On|Off</var></syntax>

<default>AuthFormDisableNoStore Off</default>

<contextlist><context>directory</context>

</contextlist>

<compatibility>Available in Apache 2.3.0 and later</compatibility>

<usage>

<p>The <directive module="mod_auth_form">AuthFormDisableNoStore</directive> flag

disables the sending of a <code>Cache-Control no-store</code> header with the

error 401 page returned when the user is not yet logged in. The purpose of the header

is to make it difficult for an ecmascript application to attempt to resubmit the

login form, and reveal the username and password to the backend application. Disable

at your own risk.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>AuthFormSitePassphrase</name>

<description>Bypass authentication checks for high traffic sites</description>

<syntax>AuthFormSitePassphrase <var>secret</var></syntax>

<default>none</default>

<contextlist><context>directory</context>

</contextlist>

<compatibility>Available in Apache 2.3.0 and later</compatibility>

<usage>

<p>The <directive module="mod_auth_form">AuthFormSitePassphrase</directive> directive

specifies a passphrase which, if present in the user session, causes Apache to

bypass authentication checks for the given URL. It can be used on high traffic websites

to reduce the load induced on authentication infrastructure.</p>

<p>The passphrase can be inserted into a user session by adding this directive to the

configuration for the <var>form-login-handler</var>. The <var>form-login-handler</var>

itself will always run the authentication checks, regardless of whether a passphrase

is specified or not.</p>

<note type="warning"><title>Warning</title>

<p>If the session is exposed to the user through the use of

<module>mod_session_cookie</module>, and the session is not protected with

<module>mod_session_crypto</module>, the passphrase is open to potential exposure

through a dictionary attack. Regardless of how the session is configured,

ensure that this directive is not used within URL spaces where private user data

could be exposed, or sensitive transactions can be conducted. Use at own risk.</p>

</note>

</usage>

</directivesynopsis>

</modulesynopsis>