From 6beeb1b708550be0d4a53b272283e17e5e35fe17 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 17:01:30 +0200 Subject: Adding upstream version 2.4.57. Signed-off-by: Daniel Baumann --- docs/manual/mod/mod_auth_form.html.en | 735 ++++++++++++++++++++++++++++++++++ 1 file changed, 735 insertions(+) create mode 100644 docs/manual/mod/mod_auth_form.html.en (limited to 'docs/manual/mod/mod_auth_form.html.en') diff --git a/docs/manual/mod/mod_auth_form.html.en b/docs/manual/mod/mod_auth_form.html.en new file mode 100644 index 0000000..113c1b9 --- /dev/null +++ b/docs/manual/mod/mod_auth_form.html.en @@ -0,0 +1,735 @@ + + + + + +mod_auth_form - Apache HTTP Server Version 2.4 + + + + + + + +
+

Modules | Directives | FAQ | Glossary | Sitemap

+

Apache HTTP Server Version 2.4

+
+
<-
+ +
+

Apache Module mod_auth_form

+
+

Available Languages:  en  | + fr 

+
+ + + + +
Description:Form authentication
Status:Base
Module Identifier:auth_form_module
Source File:mod_auth_form.c
Compatibility:Available in Apache 2.3 and later
+

Summary

+ +

Warning

+

Form authentication depends on the mod_session + 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.

+
+ +

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

+ +

HTTP basic authentication is provided by + mod_auth_basic, and HTTP digest authentication is + provided by mod_auth_digest. This module should + be combined with at least one authentication module + such as mod_authn_file and one authorization + module such as mod_authz_user.

+ +

Once the user has been successfully authenticated, the user's login + details will be stored in a session provided by mod_session. +

+ +
+ +
top
+
+

Basic Configuration

+ +

To protect a particular URL with mod_auth_form, you need to + decide where you will store your session, 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 + mod_session_cookie, and authentication will be attempted against + a file using mod_authn_file. If authentication is unsuccessful, + the user will be redirected to the form login page.

+ +

Basic example

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

The directive AuthType will enable + the mod_auth_form authentication when set to the value form. + The directives AuthFormProvider and + AuthUserFile specify that usernames + and passwords should be checked against the chosen file.

+ +

The directives Session and + SessionCookieName + session stored within an HTTP cookie on the browser. For more information + on the different options for configuring a session, read the documentation for + mod_session.

+ +

You can optionally add a + SessionCryptoPassphrase to + create an encrypted session cookie. This required the additional + module mod_session_crypto be loaded.

+ +

In the simple example above, a URL has been protected by + mod_auth_form, 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.

+
top
+
+

Standalone Login

+ +

The login form can be hosted as a standalone page, or can be provided inline on + the same page.

+ +

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 AuthFormLoginRequiredLocation + directive. Typically this login page will contain an HTML form, asking the user to + provide their usename and password.

+ +

Example login form

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

The part that does the actual login is handled by the form-login-handler. + The action of the form should point at this handler, which is configured within + Apache httpd as follows:

+ +

Form login handler example

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

The URLs specified by the + AuthFormLoginRequiredLocation directive will typically + point to a page explaining to the user that their login attempt was unsuccessful, and they + should try again. The AuthFormLoginSuccessLocation + directive specifies the URL the user should be redirected to upon successful login.

+ +

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 form-login-handler can be + reused for different areas of a website.

+ +

Example login form with location

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

Inline Login

+ +

Warning

+

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.

+
+ +

As an alternative to having a dedicated login page for a website, it is possible to + configure mod_auth_form 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.

+ +

If a non-authenticated user attempts to access a page protected by + mod_auth_form that isn't configured with a + AuthFormLoginRequiredLocation directive, + a HTTP_UNAUTHORIZED status code is returned to the browser indicating to the user + that they are not authorized to view the page.

+ +

To configure inline authentication, the administrator overrides the error document + returned by the HTTP_UNAUTHORIZED status code with a custom error document + containing the login form, as follows:

+ +

Basic inline example

AuthFormProvider file
+ErrorDocument 401 "/login.shtml"
+AuthUserFile "conf/passwd"
+AuthType form
+AuthName realm
+AuthFormLoginRequiredLocation "http://example.com/login.html"
+Session On
+SessionCookieName session path=/
+
+ +

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.

+ +

Example inline login form

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

When the end user has filled in their login details, the form will make + an HTTP POST request to the original password protected URL. + mod_auth_form 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.

+ +
top
+
+

Inline Login with Body Preservation

+ +

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.

+ +

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

+ +

To enable body preservation, add three additional fields to the login form as + per the example below.

+ +

Example with body preservation

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

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

+ +

One option is to use the mod_include module along with the + KeptBodySize directive, along with a suitable + CGI script to embed the variables in the form.

+ +

Another option is to render the login form using a CGI script or other dynamic + technology.

+ +

CGI example

AuthFormProvider file
+ErrorDocument 401 "/cgi-bin/login.cgi"
+...
+
+ +
top
+
+

Logging Out

+ +

To enable a user to log out of a particular session, configure a page to + be handled by the form-logout-handler. Any attempt to access this + URL will cause the username and password to be removed from the current + session, effectively logging the user out.

+ +

By setting the + AuthFormLogoutLocation 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.

+ +

Basic logout example

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

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 + SessionMaxAge directive to a small + value, like 1 (setting the directive to zero would mean no session age limit). +

+ +

Basic session expiry example

SetHandler form-logout-handler
+AuthFormLogoutLocation "http://example.com/loggedout.html"
+Session On
+SessionMaxAge 1
+SessionCookieName session path=/
+
+ +
top
+
+

Usernames and Passwords

+

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.

+
+
top
+

AuthFormAuthoritative Directive

+ + + + + + + + +
Description:Sets whether authorization and authentication are passed to +lower level modules
Syntax:AuthFormAuthoritative On|Off
Default:AuthFormAuthoritative On
Context:directory, .htaccess
Override:AuthConfig
Status:Base
Module:mod_auth_form
+

Normally, each authorization module listed in AuthFormProvider will attempt + to verify the user, and if the user is not found in any provider, + access will be denied. Setting the + AuthFormAuthoritative directive explicitly + to Off allows for both authentication and + authorization to be passed on to other non-provider-based modules + if there is no userID or rule + matching the supplied userID. This should only be necessary when + combining mod_auth_form with third-party modules + that are not configured with the AuthFormProvider + directive. When using such modules, the order of processing + is determined in the modules' source code and is not configurable.

+ +
+
top
+

AuthFormBody Directive

+ + + + + + + + +
Description:The name of a form field carrying the body of the request to attempt on successful login
Syntax:AuthFormBody fieldname
Default:AuthFormBody httpd_body
Context:directory
Status:Base
Module:mod_auth_form
Compatibility:Available in Apache HTTP Server 2.3.0 and later
+

The AuthFormBody directive specifies + the name of an HTML field which, if present, will contain the body of the request + to submit should login be successful.

+ +

By populating the form with fields described by + AuthFormMethod, + AuthFormMimetype and + AuthFormBody, a website can retry + a request that may have been interrupted by the login screen, or by a session + timeout.

+ +
+
top
+

AuthFormDisableNoStore Directive

+ + + + + + + + +
Description:Disable the CacheControl no-store header on the login page
Syntax:AuthFormDisableNoStore On|Off
Default:AuthFormDisableNoStore Off
Context:directory
Status:Base
Module:mod_auth_form
Compatibility:Available in Apache HTTP Server 2.3.0 and later
+

The AuthFormDisableNoStore flag + disables the sending of a Cache-Control no-store 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.

+ + +
+
top
+

AuthFormFakeBasicAuth Directive

+ + + + + + + + +
Description:Fake a Basic Authentication header
Syntax:AuthFormFakeBasicAuth On|Off
Default:AuthFormFakeBasicAuth Off
Context:directory
Status:Base
Module:mod_auth_form
Compatibility:Available in Apache HTTP Server 2.3.0 and later
+

The AuthFormFakeBasicAuth flag + determines whether a Basic Authentication 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.

+ + +
+
top
+

AuthFormLocation Directive

+ + + + + + + + +
Description:The name of a form field carrying a URL to redirect to on successful login
Syntax:AuthFormLocation fieldname
Default:AuthFormLocation httpd_location
Context:directory
Status:Base
Module:mod_auth_form
Compatibility:Available in Apache HTTP Server 2.3.0 and later
+

The AuthFormLocation directive specifies + the name of an HTML field which, if present, will contain a URL to redirect the browser to + should login be successful.

+ +
+
top
+

AuthFormLoginRequiredLocation Directive

+ + + + + + + + +
Description:The URL of the page to be redirected to should login be required
Syntax:AuthFormLoginRequiredLocation url
Default:none
Context:directory
Status:Base
Module:mod_auth_form
Compatibility:Available in Apache HTTP Server 2.3.0 and later. The use of the expression +parser has been added in 2.4.4.
+

The AuthFormLoginRequiredLocation directive + specifies the URL to redirect to should the user not be authorised to view a page. The value + is parsed using the ap_expr parser before being sent to the client. + By default, if a user is not authorised to view a page, the HTTP response code + HTTP_UNAUTHORIZED will be returned with the page specified by the + ErrorDocument directive. This directive overrides this + default.

+ +

Use this directive if you have a dedicated login page to redirect users to.

+ + +
+
top
+

AuthFormLoginSuccessLocation Directive

+ + + + + + + + +
Description:The URL of the page to be redirected to should login be successful
Syntax:AuthFormLoginSuccessLocation url
Default:none
Context:directory
Status:Base
Module:mod_auth_form
Compatibility:Available in Apache HTTP Server 2.3.0 and later. The use of the expression +parser has been added in 2.4.4.
+

The AuthFormLoginSuccessLocation directive + specifies the URL to redirect to should the user have logged in successfully. The value is + parsed using the ap_expr parser before being sent to the client. + This directive can be overridden if a form field has been defined containing another URL + using the AuthFormLocation directive.

+ +

Use this directive if you have a dedicated login URL, and you have not embedded the + destination page in the login form.

+ + +
+
top
+

AuthFormLogoutLocation Directive

+ + + + + + + + +
Description:The URL to redirect to after a user has logged out
Syntax:AuthFormLogoutLocation uri
Default:none
Context:directory
Status:Base
Module:mod_auth_form
Compatibility:Available in Apache HTTP Server 2.3.0 and later. The use of the expression +parser has been added in 2.4.4.
+

The AuthFormLogoutLocation 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 ap_expr parser before + being sent to the client.

+ +

When a URI is accessed that is served by the handler form-logout-handler, + the page specified by this directive will be shown to the end user. For example:

+ +

Example

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

An attempt to access the URI /logout/ will result in the user being logged + out, and the page /loggedout.html will be displayed. Make sure that the page + loggedout.html is not password protected, otherwise the page will not be + displayed.

+ + +
+
top
+

AuthFormMethod Directive

+ + + + + + + + +
Description:The name of a form field carrying the method of the request to attempt on successful login
Syntax:AuthFormMethod fieldname
Default:AuthFormMethod httpd_method
Context:directory
Status:Base
Module:mod_auth_form
Compatibility:Available in Apache HTTP Server 2.3.0 and later
+

The AuthFormMethod directive specifies + the name of an HTML field which, if present, will contain the method of the request + to submit should login be successful.

+ +

By populating the form with fields described by + AuthFormMethod, + AuthFormMimetype and + AuthFormBody, a website can retry + a request that may have been interrupted by the login screen, or by a session + timeout.

+ +
+
top
+

AuthFormMimetype Directive

+ + + + + + + + +
Description:The name of a form field carrying the mimetype of the body of the request to attempt on successful login
Syntax:AuthFormMimetype fieldname
Default:AuthFormMimetype httpd_mimetype
Context:directory
Status:Base
Module:mod_auth_form
Compatibility:Available in Apache HTTP Server 2.3.0 and later
+

The AuthFormMimetype directive specifies + the name of an HTML field which, if present, will contain the + mimetype of the request to submit should login be successful.

+ +

By populating the form with fields described by + AuthFormMethod, + AuthFormMimetype and + AuthFormBody, a website can retry + a request that may have been interrupted by the login screen, or by a session + timeout.

+ +
+
top
+

AuthFormPassword Directive

+ + + + + + + + +
Description:The name of a form field carrying the login password
Syntax:AuthFormPassword fieldname
Default:AuthFormPassword httpd_password
Context:directory
Status:Base
Module:mod_auth_form
Compatibility:Available in Apache HTTP Server 2.3.0 and later
+

The AuthFormPassword directive specifies + the name of an HTML field which, if present, will contain the password to be used to log + in.

+ +
+
top
+

AuthFormProvider Directive

+ + + + + + + + +
Description:Sets the authentication provider(s) for this location
Syntax:AuthFormProvider provider-name +[provider-name] ...
Default:AuthFormProvider file
Context:directory, .htaccess
Override:AuthConfig
Status:Base
Module:mod_auth_form
+

The AuthFormProvider directive sets + which provider is used to authenticate the users for this location. + The default file provider is implemented + by the mod_authn_file module. Make sure + that the chosen provider module is present in the server.

+ +

Example

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

Providers are implemented by mod_authn_dbm, + mod_authn_file, mod_authn_dbd, + mod_authnz_ldap and mod_authn_socache.

+ +
+
top
+

AuthFormSitePassphrase Directive

+ + + + + + + + +
Description:Bypass authentication checks for high traffic sites
Syntax:AuthFormSitePassphrase secret
Default:none
Context:directory
Status:Base
Module:mod_auth_form
Compatibility:Available in Apache HTTP Server 2.3.0 and later
+

The AuthFormSitePassphrase 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.

+ +

The passphrase can be inserted into a user session by adding this directive to the + configuration for the form-login-handler. The form-login-handler + itself will always run the authentication checks, regardless of whether a passphrase + is specified or not.

+ +

Warning

+

If the session is exposed to the user through the use of + mod_session_cookie, and the session is not protected with + mod_session_crypto, 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.

+
+ + +
+
top
+

AuthFormSize Directive

+ + + + + + + + +
Description:The largest size of the form in bytes that will be parsed for the login details
Syntax:AuthFormSize size
Default:AuthFormSize 8192
Context:directory
Status:Base
Module:mod_auth_form
Compatibility:Available in Apache HTTP Server 2.3.0 and later
+

The AuthFormSize directive specifies + the maximum size of the body of the request that will be parsed to find the login form.

+ +

If a login request arrives that exceeds this size, the whole request will be aborted + with the HTTP response code HTTP_REQUEST_TOO_LARGE.

+ +

If you have populated the form with fields described by + AuthFormMethod, + AuthFormMimetype and + AuthFormBody, you probably want to set this + field to a similar size as the KeptBodySize + directive.

+ + +
+
top
+

AuthFormUsername Directive

+ + + + + + + + +
Description:The name of a form field carrying the login username
Syntax:AuthFormUsername fieldname
Default:AuthFormUsername httpd_username
Context:directory
Status:Base
Module:mod_auth_form
Compatibility:Available in Apache HTTP Server 2.3.0 and later
+

The AuthFormUsername directive specifies + the name of an HTML field which, if present, will contain the username to be used to log + in.

+ +
+
+
+

Available Languages:  en  | + fr 

+
top

Comments

Notice:
This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Libera.chat, or sent to our mailing lists.
+
+ \ No newline at end of file -- cgit v1.2.3