<?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.1 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>