home *** CD-ROM | disk | FTP | other *** search
/ Chip 2004 November / CMCD1104.ISO / Software / Complet / Apache / apache_2.0.52-win32-x86-no_ssl.msi / Data.Cab / F278233_mod_auth.xml < prev    next >
Extensible Markup Language  |  2004-04-17  |  8KB  |  193 lines
  1. <?xml version="1.0"?>
  2. <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
  3. <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
  4. <!-- $Revision: 1.7.2.6 $ -->
  5.  
  6. <!--
  7.  Copyright 2002-2004 The Apache Software Foundation
  8.  
  9.  Licensed under the Apache License, Version 2.0 (the "License");
  10.  you may not use this file except in compliance with the License.
  11.  You may obtain a copy of the License at
  12.  
  13.      http://www.apache.org/licenses/LICENSE-2.0
  14.  
  15.  Unless required by applicable law or agreed to in writing, software
  16.  distributed under the License is distributed on an "AS IS" BASIS,
  17.  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  18.  See the License for the specific language governing permissions and
  19.  limitations under the License.
  20. -->
  21.  
  22. <modulesynopsis metafile="mod_auth.xml.meta">
  23.  
  24. <name>mod_auth</name>
  25. <description>User authentication using text files</description>
  26. <status>Base</status>
  27. <sourcefile>mod_auth.c</sourcefile>
  28. <identifier>auth_module</identifier>
  29. <compatibility>Available only in versions prior to 2.1</compatibility>
  30.  
  31. <summary>
  32.     <p>This module allows the use of HTTP Basic Authentication to
  33.     restrict access by looking up users in plain text password and
  34.     group files. Similar functionality and greater scalability is
  35.     provided by <module>mod_auth_dbm</module>. HTTP Digest
  36.     Authentication is provided by <module>mod_auth_digest</module>.</p>
  37. </summary>
  38. <seealso><directive module="core">Require</directive></seealso>
  39. <seealso><directive module="core">Satisfy</directive></seealso>
  40. <seealso><directive module="core">AuthName</directive></seealso>
  41. <seealso><directive module="core">AuthType</directive></seealso>
  42.  
  43. <directivesynopsis>
  44. <name>AuthGroupFile</name>
  45. <description>Sets the name of a text file containing the list
  46. of user groups for authentication</description>
  47. <syntax>AuthGroupFile <var>file-path</var></syntax>
  48. <contextlist><context>directory</context><context>.htaccess</context>
  49. </contextlist>
  50. <override>AuthConfig</override>
  51.  
  52. <usage>
  53.     <p>The <directive>AuthGroupFile</directive> directive sets the
  54.     name of a textual file containing the list of user groups for user
  55.     authentication. <var>File-path</var> is the path to the group
  56.     file. If it is not absolute, it is treated as relative to the <directive
  57.     module="core">ServerRoot</directive>.</p>
  58.  
  59.     <p>Each line of the group file contains a groupname followed by a
  60.     colon, followed by the member usernames separated by spaces.</p>
  61.  
  62.     <example><title>Example:</title>
  63.       mygroup: bob joe anne
  64.     </example> 
  65.  
  66.     <p>Note that searching large text files is <em>very</em>
  67.     inefficient; <directive module="mod_auth_dbm"
  68.     >AuthDBMGroupFile</directive> provides a much better performance.</p>
  69.  
  70.     <note type="warning"><title>Security</title>
  71.       <p>Make sure that the <directive>AuthGroupFile</directive> is
  72.       stored outside the document tree of the web-server; do <em>not</em>
  73.       put it in the directory that it protects. Otherwise, clients may
  74.       be able to download the <directive>AuthGroupFile</directive>.</p>
  75.     </note>
  76. </usage>
  77. </directivesynopsis>
  78.  
  79. <directivesynopsis>
  80. <name>AuthUserFile</name>
  81. <description>Sets the name of a text file containing the list of users and
  82. passwords for authentication</description>
  83. <syntax>AuthUserFile <var>file-path</var></syntax>
  84. <contextlist><context>directory</context><context>.htaccess</context>
  85. </contextlist>
  86. <override>AuthConfig</override>
  87.  
  88. <usage>
  89.     <p>The <directive>AuthUserFile</directive> directive sets the name
  90.     of a textual file containing the list of users and passwords for
  91.     user authentication. <var>File-path</var> is the path to the user
  92.     file. If it is not absolute (<em>i.e.</em>, if it doesn't begin
  93.     with a slash), it is treated as relative to the <directive
  94.     module="core">ServerRoot</directive>.</p>
  95.  
  96.     <p>Each line of the user file contains a username followed by
  97.     a colon, followed by the encrypted password. If the same user
  98.     ID is defined multiple times, <module>mod_auth</module> will
  99.     use the first occurrence to verify the password.</p>
  100.  
  101.     <p>The utility <a href="../programs/htpasswd.html">htpasswd</a>
  102.     which is installed as part of the binary distribution, or which
  103.     can be found in <code>src/support</code>, is used to maintain
  104.     this password file. See the <a href="../programs/htpasswd.html">man
  105.     page</a> for more details. In short:</p>
  106.  
  107.     <p>Create a password file <code>Filename</code> with
  108.     <code>username</code> as the initial ID. It will prompt for the
  109.     password:</p>
  110.  
  111.     <example>
  112.       htpasswd -c Filename username
  113.     </example>
  114.  
  115.     <p>Add or modify <code>username2</code> in the password file
  116.     <code>Filename</code>:</p>
  117.  
  118.     <example>
  119.       htpasswd Filename username2
  120.     </example>
  121.  
  122.     <p>Note that searching large text files is <em>very</em>
  123.     inefficient; <directive
  124.     module="mod_auth_dbm">AuthDBMUserFile</directive> should be used
  125.     instead.</p>
  126.  
  127.     <note type="warning"><title>Security</title>
  128.       <p>Make sure that the <directive>AuthUserFile</directive> is
  129.       stored outside the document tree of the web-server. Do
  130.       <strong>not</strong> put it in the directory that it protects.
  131.       Otherwise, clients may be able to download the
  132.       <directive>AuthUserFile</directive>.</p>
  133.     </note>
  134. </usage>
  135. </directivesynopsis>
  136.  
  137. <directivesynopsis>
  138. <name>AuthAuthoritative</name>
  139. <description>Sets whether authorization and authentication are
  140. passed to lower level modules</description>
  141. <syntax>AuthAuthoritative On|Off</syntax>
  142. <default>AuthAuthoritative On</default>
  143. <contextlist><context>directory</context><context>.htaccess</context>
  144. </contextlist>
  145. <override>AuthConfig</override>
  146.  
  147. <usage>
  148.     <p>Setting the <directive>AuthAuthoritative</directive> directive
  149.     explicitly to <code>Off</code> allows for both authentication and
  150.     authorization to be passed on to lower level modules (as defined in the
  151.     <code>modules.c</code> files) if there is <strong>no userID</strong>
  152.     or <strong>rule</strong> matching the supplied userID. If there is a
  153.     userID and/or rule specified; the usual password and access checks
  154.     will be applied and a failure will give an "Authentication Required"
  155.     reply.</p>
  156.  
  157.     <p>So if a userID appears in the database of more than one module;
  158.     or if a valid <directive module="core">Require</directive>
  159.     directive applies to more than one module; then the first module
  160.     will verify the credentials; and no access is passed on;
  161.     regardless of the <directive>AuthAuthoritative</directive> setting.</p>
  162.  
  163.     <p>A common use for this is in conjunction with one of the
  164.     database modules; such as <module>mod_auth_dbm</module>,
  165.     <code>mod_auth_msql</code>, and <module>mod_auth_anon</module>.
  166.     These modules supply the bulk of the user credential checking; but
  167.     a few (administrator) related accesses fall through to a lower
  168.     level with a well protected <directive
  169.     module="mod_auth">AuthUserFile</directive>.</p>
  170.  
  171.     <p>By default control is not passed on and an unknown userID or
  172.     rule will result in an "Authentication Required" reply. Not setting
  173.     it thus keeps the system secure and forces an NCSA compliant
  174.     behaviour.</p>
  175.  
  176.     <note type="warning"><title>Security</title>
  177.       <p>Do consider the implications of allowing a user to allow
  178.       fall-through in his .htaccess file; and verify that this is really
  179.       what you want; Generally it is easier to just secure a single
  180.       .htpasswd file, than it is to secure a database such as mSQL.
  181.       Make sure that the <directive module="mod_auth"
  182.       >AuthUserFile</directive> and the <directive module="mod_auth"
  183.       >AuthGroupFile</directive> are stored outside the document tree of
  184.       the web-server; do <em>not</em> put them in the directory that they
  185.       protect. Otherwise, clients will be able to download the <directive
  186.       module="mod_auth">AuthUserFile</directive> and the <directive
  187.       module="mod_auth">AuthGroupFile</directive>.</p>
  188.     </note>
  189. </usage>
  190. </directivesynopsis>
  191.  
  192. </modulesynopsis>
  193.