mod_auth.html revision 2de56243b49d1c39dbc467e3f9daab152c8691b8
bee2440354b4bc8796e1de0b6cbd60e1f68deba0Phill Cunnington<html xmlns="http://www.w3.org/TR/xhtml1/strict"><head><!--
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster This file is generated from xml source: DO NOT EDIT
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster --><title>mod_auth- Apache HTTP Server</title><link href="/style/manual.css" type="text/css" rel="stylesheet"/></head><body><blockquote><div align="center"><img src="/images/sub.gif" alt="[APACHE DOCUMENTATION]"/><h3>Apache HTTP Server Version 2.0</h3></div><h1 align="center">Apache Module mod_auth</h1><table cellspacing="1" cellpadding="0" bgcolor="#cccccc"><tr><td><table bgcolor="#ffffff"><tr><td valign="top"><span class="help">Description:</span></td><td>User authentication using text files</td></tr><tr><td><a href="module-dict.html#Status" class="help">Status:</a></td><td>Base</td></tr><tr><td><a href="module-dict.html#ModuleIdentifier" class="help">Module Identifier:</a></td><td>auth_module</td></tr></table></td></tr></table><h2>Summary</h2>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster <p>This module allows the use of HTTP Basic Authentication to
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster restrict access by looking up users in plain text password and
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster group files. Similar functionality and greater scalability is
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster provided by <code><a href="mod_auth_dbm.html">mod_auth_dbm</a></code>. HTTP Digest
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster Authentication is provided by
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster <code><a href="mod_auth_digest.html">mod_auth_digest</a></code>.</p>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<h2>Directives</h2><ul><li><a href="#authauthoritative">AuthAuthoritative</a></li><li><a href="#authgroupfile">AuthGroupFile</a></li><li><a href="#authuserfile">AuthUserFile</a></li></ul><p><strong>See also </strong></p><ul><li><a href="core.html#require" class="directive"><code class="directive">Require</code></a></li><li><a href="core.html#satisfy" class="directive"><code class="directive">Satisfy</code></a></li><li><a href="core.html#authname" class="directive"><code class="directive">AuthName</code></a></li><li><a href="core.html#authtype" class="directive"><code class="directive">AuthType</code></a></li></ul><hr/><h2><a name="AuthAuthoritative">AuthAuthoritative</a> <a name="authauthoritative">Directive</a></h2><table cellpadding="1" cellspacing="0" border="0" bgcolor="#cccccc"><tr><td><table bgcolor="#ffffff"><tr><td><strong>Description: </strong></td><td>Sets whether authorization and authentication are
8af80418ba1ec431c8027fa9668e5678658d3611Allan Fosterpassed to lower level modules</td></tr><tr><td><a href="directive-dict.html#Syntax" class="help">Syntax:</a></td><td>AuthAuthoritative on|off</td></tr><tr><td><a href="directive-dict.html#Default" class="help">Default:</a></td><td><code>AuthAuthoritative on</code></td></tr><tr><td><a href="directive-dict.html#Context" class="help">Context:</a></td><td>directory, .htaccess</td></tr><tr><td><a href="directive-dict.html#Override" class="help">Override:</a></td><td>AuthConfig</td></tr><tr><td><a href="directive-dict.html#Status" class="help">Status:</a></td><td>Base</td></tr><tr><td><a href="directive-dict.html#Module" class="help">Module:</a></td><td>mod_auth</td></tr></table></td></tr></table>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<blockquote><table><tr><td bgcolor="#e0e5f5">This information has not been updated for Apache 2.0, which
8af80418ba1ec431c8027fa9668e5678658d3611Allan Fosteruses a different system for module ordering.</td></tr></table></blockquote>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster <p>Setting the <code class="directive">AuthAuthoritative</code> directive
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster explicitly to <strong>'off'</strong> allows for both
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster authentication and authorization to be passed on to lower level
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster modules (as defined in the <code>Configuration</code> and
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster <code>modules.c</code> files) if there is <strong>no
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster userID</strong> or <strong>rule</strong> matching the supplied
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster userID. If there is a userID and/or rule specified; the usual
f4a2472d1b182b04ec3b4693e484d51b20ba982cPeter Major password and access checks will be applied and a failure will give
8a3bcf10e6c2ced4eceb11ca204384c3551bb81dKohei Tamura an Authorization Required reply.</p>
bee2440354b4bc8796e1de0b6cbd60e1f68deba0Phill Cunnington <p>So if a userID appears in the database of more than one module;
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster or if a valid <a href="core.html#require" class="directive"><code class="directive">Require</code></a>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster directive applies to more than one module; then the first module
f4a2472d1b182b04ec3b4693e484d51b20ba982cPeter Major will verify the credentials; and no access is passed on;
f4a2472d1b182b04ec3b4693e484d51b20ba982cPeter Major regardless of the AuthAuthoritative setting.</p>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster <p>A common use for this is in conjunction with one of the
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster database modules; such as <code><a href="auth_dbm.html">auth_dbm</a></code>,
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster <code>mod_auth_msql</code>, and <code><a href="mod_auth_anon.html">mod_auth_anon</a></code>.
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster These modules supply the bulk of the user credential checking; but
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster a few (administrator) related accesses fall through to a lower
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster level with a well protected <a href="#authuserfile" class="directive"><code class="directive">AuthUserFile</code></a>.</p>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster <p>By default; control is not passed on; and an unknown userID or
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster rule will result in an Authorization Required reply. Not setting
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster it thus keeps the system secure; and forces an NCSA compliant
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster behaviour.</p>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster <blockquote><table><tr><td bgcolor="#e0e5f5"><p align="center"><strong>Security</strong></p> Do consider the implications of
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster allowing a user to allow fall-through in his .htaccess file; and
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster verify that this is really what you want; Generally it is easier
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster to just secure a single .htpasswd file, than it is to secure a
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster database such as mSQL. Make sure that the <a href="#authuserfile" class="directive"><code class="directive">AuthUserFile</code></a> is stored outside the
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster document tree of the web-server; do <em>not</em> put it in the
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster directory that it protects. Otherwise, clients will be able to
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster download the <a href="#authuserfile" class="directive"><code class="directive">AuthUserFile</code></a>.
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<hr/><h2><a name="AuthGroupFile">AuthGroupFile</a> <a name="authgroupfile">Directive</a></h2><table cellpadding="1" cellspacing="0" border="0" bgcolor="#cccccc"><tr><td><table bgcolor="#ffffff"><tr><td><strong>Description: </strong></td><td>Sets the name of a text file containing the list
8af80418ba1ec431c8027fa9668e5678658d3611Allan Fosterof user groups for authentication</td></tr><tr><td><a href="directive-dict.html#Syntax" class="help">Syntax:</a></td><td>AuthGroupFile <em>file-path</em></td></tr><tr><td><a href="directive-dict.html#Context" class="help">Context:</a></td><td>directory, .htaccess</td></tr><tr><td><a href="directive-dict.html#Override" class="help">Override:</a></td><td>AuthConfig</td></tr><tr><td><a href="directive-dict.html#Status" class="help">Status:</a></td><td>Base</td></tr><tr><td><a href="directive-dict.html#Module" class="help">Module:</a></td><td>mod_auth</td></tr></table></td></tr></table>
cadf2da54bbf0eee3b06ecb0d33137230f9629daDirk Hogan <p>The <code class="directive">AuthGroupFile</code> directive sets the
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster name of a textual file containing the list of user groups for user
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster authentication. <em>File-path</em> is the path to the group
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster file. If it is not absolute (<em>i.e.</em>, if it doesn't begin
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster with a slash), it is treated as relative to the <a href="core.html#serverroot" class="directive"><code class="directive">ServerRoot</code></a>.</p>
60e9e896a1a7a9e62db162e1e9fb6b3c2df50c33Quentin CASTEL <p>Each line of the group file contains a groupname followed by a
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster colon, followed by the member usernames separated by spaces.
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster Example:</p>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code>mygroup: bob joe anne</code></td></tr></table></blockquote>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster <p>Note that searching large text files is <em>very</em>
f4a2472d1b182b04ec3b4693e484d51b20ba982cPeter Major inefficient; <a href="mod_auth_dbm.html#authdbmgroupfile" class="directive"><code class="directive">AuthDBMGroupFile</code></a> should be used
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster instead.</p>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<blockquote><table><tr><td bgcolor="#e0e5f5"><p align="center"><strong>Security</strong></p>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster <p>Make sure that the AuthGroupFile is stored outside
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster the document tree of the web-server; do <em>not</em> put it in
d5cf854d33975d4f1a272ed54280d2e9c75fc9d6sachiko the directory that it protects. Otherwise, clients will be able
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster to download the AuthGroupFile.</p>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<hr/><h2><a name="AuthUserFile">AuthUserFile</a> <a name="authuserfile">Directive</a></h2><table cellpadding="1" cellspacing="0" border="0" bgcolor="#cccccc"><tr><td><table bgcolor="#ffffff"><tr><td><strong>Description: </strong></td><td>Sets the name of a text file containing the list of users and
8af80418ba1ec431c8027fa9668e5678658d3611Allan Fosterpasswords for authentication</td></tr><tr><td><a href="directive-dict.html#Syntax" class="help">Syntax:</a></td><td>AuthUserFile <em>file-path</em></td></tr><tr><td><a href="directive-dict.html#Context" class="help">Context:</a></td><td>directory, .htaccess</td></tr><tr><td><a href="directive-dict.html#Override" class="help">Override:</a></td><td>AuthConfig</td></tr><tr><td><a href="directive-dict.html#Status" class="help">Status:</a></td><td>Base</td></tr><tr><td><a href="directive-dict.html#Module" class="help">Module:</a></td><td>mod_auth</td></tr></table></td></tr></table>
d5cf854d33975d4f1a272ed54280d2e9c75fc9d6sachiko <p>The <code class="directive">AuthUserFile</code> directive sets the name
bee2440354b4bc8796e1de0b6cbd60e1f68deba0Phill Cunnington of a textual file containing the list of users and passwords for
c42550c0e86e2c3f821f5e754ea8ba52d8bb5427Tony Bamford user authentication. <em>File-path</em> is the path to the user
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster file. If it is not absolute (<em>i.e.</em>, if it doesn't begin
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster with a slash), it is treated as relative to the <a href="core.html#serverroot" class="directive"><code class="directive">ServerRoot</code></a>.</p>
c42550c0e86e2c3f821f5e754ea8ba52d8bb5427Tony Bamford <p>Each line of the user file file contains a username followed by
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster a colon, followed by the <code>crypt()</code> encrypted
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster password. The behavior of multiple occurrences of the same user is
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster undefined.</p>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster <p>The utility <a href="/programs/htpasswd.html">htpasswd</a>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster which is installed as part of the binary distribution, or which
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster can be found in <code>src/support</code>, is used to maintain
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster this password file. See the <code>man</code> page for more
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster details. In short:</p>
f4a2472d1b182b04ec3b4693e484d51b20ba982cPeter Major <p>Create a password file 'Filename' with 'username' as the
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster initial ID. It will prompt for the password:</p>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code>htpasswd -c Filename username</code></td></tr></table></blockquote>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<p>Adds or modifies in password file 'Filename' the 'username':</p>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code>htpasswd Filename username2</code></td></tr></table></blockquote>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster <p>Note that searching large text files is <em>very</em>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster inefficient; <a href="mod_auth_dbm.html#authdbmuserfile" class="directive"><code class="directive">AuthDBMUserFile</code></a> should be used
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster instead.</p>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<blockquote><table><tr><td bgcolor="#e0e5f5"><p align="center"><strong>Security</strong></p><p>Make sure that the AuthUserFile is
8af80418ba1ec431c8027fa9668e5678658d3611Allan Fosterstored outside the document tree of the web-server; do <em>not</em>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Fosterput it in the directory that it protects. Otherwise, clients will be
8af80418ba1ec431c8027fa9668e5678658d3611Allan Fosterable to download the AuthUserFile.</p></td></tr></table></blockquote>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<hr/></blockquote><h3 align="center">Apache HTTP Server Version 2.0</h3><a href="./"><img src="/images/index.gif" alt="Index"/></a><a href="../"><img src="/images/home.gif" alt="Home"/></a></body></html>
