mod_auth.html revision 19571734da8573ce05afdaf0d33e67b41400215d
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington<HTML>
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington<HEAD>
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington<TITLE>Apache module mod_auth</TITLE>
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington</HEAD>
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington<BODY
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington BGCOLOR="#FFFFFF"
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington TEXT="#000000"
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington LINK="#0000FF"
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington VLINK="#000080"
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington ALINK="#FF0000"
71b128a7314b40bf2b9740cfa80f6cdba76740e8Phill Cunnington>
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington<!--#include virtual="header.html" -->
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington<H1 ALIGN="CENTER">Module mod_auth</H1>
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington
2dd75eff92ef66e22cca286b6f4fe5a9c929af9dPhill Cunnington<P>This module provides for user authentication using text files.
71b128a7314b40bf2b9740cfa80f6cdba76740e8Phill Cunnington
5ca5216a4064895b869095def90c6a6a2c5d255fJames Phillpotts<P><A
5ca5216a4064895b869095def90c6a6a2c5d255fJames PhillpottsHREF="module-dict.html#Status"
5ca5216a4064895b869095def90c6a6a2c5d255fJames PhillpottsREL="Help"
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington><STRONG>Status:</STRONG></A> Base
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington<BR>
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington<A
2dd75eff92ef66e22cca286b6f4fe5a9c929af9dPhill CunningtonHREF="module-dict.html#SourceFile"
71b128a7314b40bf2b9740cfa80f6cdba76740e8Phill CunningtonREL="Help"
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington><STRONG>Source File:</STRONG></A> mod_auth.c
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington<BR>
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington<A
a093731116a8c24d49b903df7602cf586e499b45Phill CunningtonHREF="module-dict.html#ModuleIdentifier"
a093731116a8c24d49b903df7602cf586e499b45Phill CunningtonREL="Help"
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington><STRONG>Module Identifier:</STRONG></A> auth_module
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington</P>
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington<H2>Summary</H2>
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington<P>This module allows the use of HTTP Basic Authentication to restrict
a093731116a8c24d49b903df7602cf586e499b45Phill Cunningtonaccess by looking up users in plain text password and group files.
a093731116a8c24d49b903df7602cf586e499b45Phill CunningtonSimilar functionality and greater scalability is provided by <A
a093731116a8c24d49b903df7602cf586e499b45Phill CunningtonHREF="mod_auth_dbm.html">mod_auth_dbm</A> and <A
a093731116a8c24d49b903df7602cf586e499b45Phill CunningtonHREF="mod_auth_db.html">mod_auth_db</A>. HTTP Digest Authentication
5db031755ab3a8762e266f96f5d74832548d330bPhill Cunningtonis provided by <A HREF="mod_auth_digest.html">mod_auth_digest</A>.
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington
5db031755ab3a8762e266f96f5d74832548d330bPhill Cunnington<H2>Directives</H2>
5db031755ab3a8762e266f96f5d74832548d330bPhill Cunnington
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington<UL>
5db031755ab3a8762e266f96f5d74832548d330bPhill Cunnington<LI><A HREF="#authgroupfile">AuthGroupFile</A>
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington<LI><A HREF="#authuserfile">AuthUserFile</A>
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington<LI><A HREF="#authauthoritative">AuthAuthoritative</A>
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington</UL>
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington<P>See also: <A HREF="core.html#require">require</A>
a093731116a8c24d49b903df7602cf586e499b45Phill Cunningtonand <A HREF="core.html#satisfy">satisfy</A>.</P>
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington
5db031755ab3a8762e266f96f5d74832548d330bPhill Cunnington<HR>
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington<H2><A NAME="authgroupfile">AuthGroupFile</A> directive</H2>
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington<!--%plaintext &lt;?INDEX {\tt AuthGroupFile} directive&gt; -->
5db031755ab3a8762e266f96f5d74832548d330bPhill Cunnington<A
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington HREF="directive-dict.html#Syntax"
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington REL="Help"
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington><STRONG>Syntax:</STRONG></A> AuthGroupFile <EM>file-path</EM><BR>
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington<A
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington HREF="directive-dict.html#Context"
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington REL="Help"
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington><STRONG>Context:</STRONG></A> directory, .htaccess<BR>
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington<A
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington HREF="directive-dict.html#Override"
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington REL="Help"
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington><STRONG>Override:</STRONG></A> AuthConfig<BR>
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington<A
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington HREF="directive-dict.html#Status"
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington REL="Help"
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington><STRONG>Status:</STRONG></A> Base<BR>
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington<A
5db031755ab3a8762e266f96f5d74832548d330bPhill Cunnington HREF="directive-dict.html#Module"
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington REL="Help"
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington><STRONG>Module:</STRONG></A> mod_auth<P>
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington
a093731116a8c24d49b903df7602cf586e499b45Phill CunningtonThe AuthGroupFile directive sets the name of a textual file containing the list
5db031755ab3a8762e266f96f5d74832548d330bPhill Cunningtonof user groups for user authentication. <EM>File-path</EM> is the path
a093731116a8c24d49b903df7602cf586e499b45Phill Cunningtonto the group file. If it is not absolute (<EM>i.e.</EM>, if it
a093731116a8c24d49b903df7602cf586e499b45Phill Cunningtondoesn't begin with a slash), it is treated as relative to the ServerRoot.
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington<P>
bf36b5c30cb4d181af39c91096b86fdf628ca189James PhillpottsEach line of the group file contains a groupname followed by a colon, followed
5ca5216a4064895b869095def90c6a6a2c5d255fJames Phillpottsby the member usernames separated by spaces. Example:
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington<BLOCKQUOTE><CODE>mygroup: bob joe anne</CODE></BLOCKQUOTE>
a093731116a8c24d49b903df7602cf586e499b45Phill CunningtonNote that searching large text files is <EM>very</EM> inefficient;
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington<A HREF="mod_auth_dbm.html#authdbmgroupfile">AuthDBMGroupFile</A> should
a093731116a8c24d49b903df7602cf586e499b45Phill Cunningtonbe used instead.<P>
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington
a093731116a8c24d49b903df7602cf586e499b45Phill CunningtonSecurity: make sure that the AuthGroupFile is stored outside the
a093731116a8c24d49b903df7602cf586e499b45Phill Cunningtondocument tree of the web-server; do <EM>not</EM> put it in the directory that
a093731116a8c24d49b903df7602cf586e499b45Phill Cunningtonit protects. Otherwise, clients will be able to download the AuthGroupFile.<P>
5db031755ab3a8762e266f96f5d74832548d330bPhill Cunnington
a093731116a8c24d49b903df7602cf586e499b45Phill CunningtonSee also <A HREF="core.html#authname">AuthName</A>,
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington<A HREF="core.html#authtype">AuthType</A> and
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington<A HREF="#authuserfile">AuthUserFile</A>.<P><HR>
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington<H2><A NAME="authuserfile">AuthUserFile</A> directive</H2>
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington<!--%plaintext &lt;?INDEX {\tt AuthUserFile} directive&gt; -->
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington<A
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington HREF="directive-dict.html#Syntax"
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington REL="Help"
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington><STRONG>Syntax:</STRONG></A> AuthUserFile <EM>file-path</EM><BR>
a093731116a8c24d49b903df7602cf586e499b45Phill Cunnington<A
HREF="directive-dict.html#Context"
REL="Help"
><STRONG>Context:</STRONG></A> directory, .htaccess<BR>
<A
HREF="directive-dict.html#Override"
REL="Help"
><STRONG>Override:</STRONG></A> AuthConfig<BR>
<A
HREF="directive-dict.html#Status"
REL="Help"
><STRONG>Status:</STRONG></A> Base<BR>
<A
HREF="directive-dict.html#Module"
REL="Help"
><STRONG>Module:</STRONG></A> mod_auth<P>
The AuthUserFile directive sets the name of a textual file containing
the list of users and passwords for user
authentication. <EM>File-path</EM> is the path to the user
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 ServerRoot.
<P> Each line of the user file file contains a username followed
by a colon, followed by the crypt() encrypted password. The behavior
of multiple occurrences of the same user is undefined.
<P>
The utility <a href="/programs/htpasswd.html">htpasswd</a> which is
installed as part of the binary distribution, or which can be found in
<code>src/support</code>, is used to maintain this password file. See
the <code>man</code> page for more details. In short
<p>
<blockquote>
<code>htpasswd -c Filename username</code><br>
Create a password file 'Filename' with 'username'
as the initial ID. It will prompt for the password.
<code>htpasswd Filename username2</code><br>
Adds or modifies in password file 'Filename' the 'username'.
</blockquote>
<P> Note that
searching large text files is <EM>very</EM> inefficient;
<A HREF="mod_auth_dbm.html#authdbmuserfile">AuthDBMUserFile</A> should be
used instead.
<P>
Security: make sure that the AuthUserFile 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 AuthUserFile.<P>
See also <A HREF="core.html#authname">AuthName</A>,
<A HREF="core.html#authtype">AuthType</A> and
<A HREF="#authgroupfile">AuthGroupFile</A>.<P>
<HR>
<H2><A NAME="authauthoritative">AuthAuthoritative</A> directive</H2>
<!--%plaintext &lt;?INDEX {\tt AuthAuthoritative} directive&gt; -->
<A
HREF="directive-dict.html#Syntax"
REL="Help"
><STRONG>Syntax:</STRONG></A> AuthAuthoritative on|off<BR>
<A
HREF="directive-dict.html#Default"
REL="Help"
><STRONG>Default:</STRONG></A> <CODE>AuthAuthoritative on</CODE><BR>
<A
HREF="directive-dict.html#Context"
REL="Help"
><STRONG>Context:</STRONG></A> directory, .htaccess<BR>
<A
HREF="directive-dict.html#Override"
REL="Help"
><STRONG>Override:</STRONG></A> AuthConfig<BR>
<A
HREF="directive-dict.html#Status"
REL="Help"
><STRONG>Status:</STRONG></A> Base<BR>
<A
HREF="directive-dict.html#Module"
REL="Help"
><STRONG>Module:</STRONG></A> mod_auth<P>
Setting the AuthAuthoritative directive explicitly to <STRONG>'off'</STRONG>
allows for both authentication and authorization to be passed on to
lower level modules (as defined in the <CODE>Configuration</CODE> and
<CODE>modules.c</CODE> files) 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>
So if a userID appears in the database of more than one module; or if
a valid <CODE>Require</CODE> directive applies to more than one module; then the
first module will verify the credentials; and no access is passed on;
regardless of the AuthAuthoritative setting.
<P>
A common use for this is in conjunction with one of the database
modules; such as <A
HREF="mod_auth_db.html"><CODE>mod_auth_db.c</CODE></A>, <A
HREF="mod_auth_dbm.html"><CODE>mod_auth_dbm.c</CODE></A>,
<CODE>mod_auth_msql.c</CODE>, and <A
HREF="mod_auth_anon.html"><CODE>mod_auth_anon.c</CODE></A>. These modules
supply the bulk of the user credential checking; but a few
(administrator) related accesses fall through to a lower level with a
well protected AuthUserFile.
<P>
<A
HREF="directive-dict.html#Default"
REL="Help"
><STRONG>Default:</STRONG></A> 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>
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 such as mSQL. Make
sure that the AuthUserFile 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
AuthUserFile.
<P>
See also <A HREF="core.html#authname">AuthName</A>,
<A HREF="core.html#authtype">AuthType</A> and
<A HREF="#authgroupfile">AuthGroupFile</A>.<P>
<!--#include virtual="footer.html" -->
</BODY>
</HTML>