| <?xml version="1.0"?> |
| <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd"> |
| <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?> |
| <!-- $LastChangedRevision$ --> |
| |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| |
| <modulesynopsis metafile="mod_auth_form.xml.meta"> |
| |
| <name>mod_auth_form</name> |
| <description>Form authentication</description> |
| <status>Base</status> |
| <sourcefile>mod_auth_form.c</sourcefile> |
| <identifier>auth_form_module</identifier> |
| <compatibility>Available in Apache 2.3 and later</compatibility> |
| |
| <summary> |
| <note type="warning"><title>Warning</title> |
| <p>Form authentication depends on the <module>mod_session</module> |
| modules, and these modules make use of HTTP cookies, and as such can fall |
| victim to Cross Site Scripting attacks, or expose potentially private |
| information to clients. Please ensure that the relevant risks have |
| been taken into account before enabling the session functionality on |
| your server.</p> |
| </note> |
| |
| <p>This module allows the use of an HTML login form to restrict access |
| by looking up users in the given providers. HTML forms require |
| significantly more configuration than the alternatives, however an |
| HTML login form can provide a much friendlier experience for end users. |
| </p> |
| |
| <p>HTTP basic authentication is provided by |
| <module>mod_auth_basic</module>, and HTTP digest authentication is |
| provided by <module>mod_auth_digest</module>. This module should |
| 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><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> |
| <highlight language="config"> |
| <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> |
| </highlight> |
| </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> and |
| <directive module="mod_session_cookie">SessionCookieName</directive> |
| 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>You can optionally add a |
| <directive module="mod_session_crypto">SessionCryptoPassphrase</directive> to |
| create an encrypted session cookie. This required the additional |
| module <module>mod_session_crypto</module> be loaded.</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> |
| <highlight language="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> |
| </highlight> |
| </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 httpd as follows:</p> |
| |
| <example><title>Form login handler example</title> |
| <highlight language="config"> |
| <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> |
| </highlight> |
| </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> |
| <highlight language="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" /> |
| <input type="hidden" name="httpd_location" value="http://example.com/success.html" /> |
| </form> |
| </highlight> |
| </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> |
| <highlight language="config"> |
| AuthFormProvider file |
| ErrorDocument 401 "/login.shtml" |
| AuthUserFile "conf/passwd" |
| AuthType form |
| AuthName realm |
| AuthFormLoginRequiredLocation "http://example.com/login.html" |
| Session On |
| SessionCookieName session path=/ |
| </highlight> |
| </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> |
| <highlight language="html"> |
| <form method="POST" <strong>action=""</strong>> |
| Username: <input type="text" name="httpd_username" value="" /> |
| Password: <input type="password" name="httpd_password" value="" /> |
| <input type="submit" name="login" value="Login" /> |
| </form> |
| </highlight> |
| </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 |
| reauthenticate, 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 httpd, 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> |
| <highlight language="html"> |
| <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" /> |
| <br/> <strong><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" /></strong><br/> |
| </form> |
| </highlight> |
| </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="mod_request">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> |
| <highlight language="config"> |
| AuthFormProvider file |
| ErrorDocument 401 "/cgi-bin/login.cgi" |
| ... |
| </highlight> |
| </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> |
| <highlight language="config"> |
| SetHandler form-logout-handler |
| AuthName realm |
| AuthFormLogoutLocation "http://example.com/loggedout.html" |
| Session On |
| SessionCookieName session path=/ |
| </highlight> |
| </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> |
| <highlight language="config"> |
| SetHandler form-logout-handler |
| AuthFormLogoutLocation "http://example.com/loggedout.html" |
| Session On |
| SessionMaxAge 1 |
| SessionCookieName session path=/ |
| </highlight> |
| </example> |
| |
| </section> |
| |
| <section id="urlencoding"><title>Usernames and Passwords</title> |
| <p>Note that form submission involves URLEncoding the form data: |
| in this case the username and password. You should therefore |
| pick usernames and passwords that avoid characters that are |
| URLencoded in form submission, or you may get unexpected results.</p> |
| </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> |
| <highlight language="config"> |
| <Location "/secure"> |
| AuthType form |
| AuthName "private area" |
| AuthFormProvider dbm |
| AuthDBMType SDBM |
| AuthDBMUserFile "/www/etc/dbmpasswd" |
| Require valid-user |
| #... |
| </Location> |
| </highlight> |
| </example> |
| |
| <p>Providers are implemented by <module>mod_authn_dbm</module>, |
| <module>mod_authn_file</module>, <module>mod_authn_dbd</module>, |
| <module>mod_authnz_ldap</module> and <module>mod_authn_socache</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 HTTP Server 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 HTTP Server 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 HTTP Server 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 HTTP Server 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 HTTP Server 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 |
| mimetype of the request 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 HTTP Server 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>AuthFormSize <var>size</var></syntax> |
| <default>8192</default> |
| <contextlist><context>directory</context> |
| </contextlist> |
| <compatibility>Available in Apache HTTP Server 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="mod_request">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 HTTP Server 2.3.0 and later. The use of the expression |
| parser has been added in 2.4.4.</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. The value |
| is parsed using the <a href="../expr.html">ap_expr</a> parser before being sent to the client. |
| 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="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 HTTP Server 2.3.0 and later. The use of the expression |
| parser has been added in 2.4.4.</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. The value is |
| parsed using the <a href="../expr.html">ap_expr</a> parser before being sent to the client. |
| 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 HTTP Server 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 HTTP Server 2.3.0 and later. The use of the expression |
| parser has been added in 2.4.4.</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. The value is parsed using the <a href="../expr.html">ap_expr</a> parser before |
| being sent to the client.</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> |
| <highlight language="config"> |
| <Location "/logout"> |
| SetHandler form-logout-handler |
| AuthFormLogoutLocation "http://example.com/loggedout.html" |
| Session on |
| #... |
| </Location> |
| </highlight> |
| </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 HTTP Server 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 <code>ecmascript</code> 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 HTTP Server 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 httpd 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> |