docs/manual/mod/mod_authz_groupfile.xml

<?xml version="1.0"?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
<modulesynopsis>

<name>mod_authz_groupfile</name>
<description>Group authorization using plaintext files</description>
<status>Extension</status>
<sourcefile>mod_authz_groupfile.c</sourcefile>
<identifier>authz_groupfile_module</identifier>
<compatibility>Available in Apache 2.0.42 and later</compatibility>

<summary>
    <p>This module provides authorization capabilities so that
       authenticated users can be allowed or denied access to portions
       of the web site by group membership. Similar functionality is
       provided by <module>mod_authz_dbm</module>.</p>
</summary>

<seealso><directive module="core">Require</directive></seealso>
<seealso><directive module="core">Satisfy</directive></seealso>

<directivesynopsis>
<name>AuthGroupFile</name>
<description>Sets the name of a text file containing the list
of user groups for authentication</description>
<syntax>AuthGroupFile <em>file-path</em></syntax>
<contextlist>
  <context>directory</context>
  <context>.htaccess</context>
</contextlist>
<override>AuthConfig</override>

<usage>
    <p>The <directive>AuthGroupFile</directive> directive sets the
    name of a textual file containing the list of user groups for user
    authentication.  <em>File-path</em> is the path to the group
    file. If it is not absolute (<em>i.e.</em>, if it doesn't begin
    with a slash), it is treated as relative to the <directive
    module="core">ServerRoot</directive>.</p>

    <p>Each line of the group file contains a groupname followed by a
    colon, followed by the member usernames separated by spaces.
    Example:</p> 

    <example>mygroup: bob joe anne</example> 

    <p>Note that searching large text files is <em>very</em>
    inefficient; <directive
    module="mod_authz_dbm">AuthDBMGroupFile</directive> should be used
    instead.</p>

    <note><title>Security</title>
    <p>Make sure that the <directive>AuthGroupFile</directive> is
	stored outside the document tree of the web-server; do <em>not</em>
	put it in the directory that it protects. Otherwise, clients will
	be able to download the <directive>AuthGroupFile</directive>.</p>
    </note>
</usage>
</directivesynopsis>

<directivesynopsis>
<name>AuthzGroupFileAuthoritative</name>
<description>Sets whether authorization will be passed on to lower level modules</description>
<syntax>AuthzGroupFileAuthoritative on|off</syntax>
<default>AuthzGroupFileAuthoritative on</default>
<contextlist>
  <context>directory</context>
  <context>.htaccess</context>
</contextlist>
<override>AuthConfig</override>

<usage>

    <p>Setting the <directive>AuthzGroupFileAuthoritative</directive>
    directive explicitly to <strong>'off'</strong> allows for
    authorization to be passed on to lower level modules (as defined in
    the <code>Configuration</code> and <code>modules.c</code> file if
    there is <strong>no userID</strong> or <strong>rule</strong> matching
    the supplied userID. If there is a userID and/or rule specified; the
    usual password and access checks will be applied and a failure will
    give an Authorization Required reply.</p>

    <p>So if a valid <directive module="core">Require</directive>
    directive applies to more than one module; then the first module
    will verify the credentials; and no access is passed on;
    regardless of the <directive>AuthzGroupFileAuthoritative</directive>
    setting.</p>

    <p>By default, control is not passed on and an unknown userID
    or rule will result in an Authorization Required reply. Not
    setting it thus keeps the system secure and forces an NCSA
    compliant behaviour.</p>

    <p>Security: Do consider the implications of allowing a user to
    allow fall-through in his .htaccess file; and verify that this
    is really what you want; Generally it is easier to just secure
    a single .htpasswd file, than it is to secure a database which
    might have more access interfaces.</p>
</usage>
</directivesynopsis>

</modulesynopsis>