docs/manual/howto/auth.xml - httpd - Git at Google

 <?xml version='1.0' encoding='UTF-8' ?>
 <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
 <!-- $LastChangedRevision$ -->

 <!--
  Copyright 2003-2005 The Apache Software Foundation or its licensors, as
  applicable.

  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
 -->

 <manualpage metafile="auth.xml.meta">
 <parentdocument href="./">How-To / Tutorials</parentdocument>

 <title>Authentication, Authorization and Access Control</title>

 <summary>
     <p>Authentication is any process by which you verify that
     someone is who they claim they are. Authorization is any
     process by which someone is allowed to be where they want to
     go, or to have information that they want to have.</p>
 </summary>

 <section id="related"><title>Related Modules and Directives</title>

 <p>There are three types of modules involved in the authentication and
 authorization process.  You will usually need to choose at least one
 module from each group.</p>

 <ul>
   <li>Authentication type (see the
       <directive module="core">AuthType</directive> directive)
     <ul>
       <li><module>mod_auth_basic</module></li>
       <li><module>mod_auth_digest</module></li>
     </ul>
   </li>
   <li>Authentication provider
     <ul>
       <li><module>mod_authn_alias</module></li>
       <li><module>mod_authn_anon</module></li>
       <li><module>mod_authn_core</module></li>
       <li><module>mod_authn_dbd</module></li>
       <li><module>mod_authn_dbm</module></li>
       <li><module>mod_authn_default</module></li>
       <li><module>mod_authn_file</module></li>
       <li><module>mod_authnz_ldap</module></li>
     </ul>
   </li>
   <li>Authorization (see the
       <directive module="mod_authz_core">Require</directive> and
       <directive module="mod_authz_core">Reject</directive> directives)
     <ul>
       <li><module>mod_authnz_ldap</module></li>
       <li><module>mod_authz_core</module></li>
       <li><module>mod_authz_dbm</module></li>
       <li><module>mod_authz_default</module></li>
       <li><module>mod_authz_groupfile</module></li>
       <li><module>mod_authz_owner</module></li>
       <li><module>mod_authz_user</module></li>
     </ul>
   </li>
 </ul>

   <p>The module <module>mod_authnz_ldap</module> is both an
   authentication and authorization provider.  The module
   <module>mod_authn_alias</module> is not an authentication provider
   in itself, but allows other authentication providers to be
   configured in a flexible manner.</p>

   <p>The modules <module>mod_authn_core</module> and <module>mod_authz_core
   </module> should always be loaded. These module provide the core
   directives and functionality that is common to all authentication
   and authorization providers.</p>

 </section>

 <section id="introduction"><title>Introduction</title>
     <p>If you have information on your web site that is sensitive
     or intended for only a small group of people, the techniques in
     this article will help you make sure that the people that see
     those pages are the people that you wanted to see them.</p>

     <p>This article covers the "standard" way of protecting parts
     of your web site that most of you are going to use.</p>
 </section>

 <section id="theprerequisites"><title>The Prerequisites</title>
     <p>The directives discussed in this article will need to go
     either in your main server configuration file (typically in a
     <directive module="core" type="section">Directory</directive> section), or
     in per-directory configuration files (<code>.htaccess</code> files).</p>

     <p>If you plan to use <code>.htaccess</code> files, you will
     need to have a server configuration that permits putting
     authentication directives in these files. This is done with the
     <directive module="core">AllowOverride</directive> directive, which
     specifies which directives, if any, may be put in per-directory
     configuration files.</p>

     <p>Since we're talking here about authentication, you will need
     an <directive module="core">AllowOverride</directive> directive like the
     following:</p>

     <example>
       AllowOverride AuthConfig
     </example>

     <p>Or, if you are just going to put the directives directly in
     your main server configuration file, you will of course need to
     have write permission to that file.</p>

     <p>And you'll need to know a little bit about the directory
     structure of your server, in order to know where some files are
     kept. This should not be terribly difficult, and I'll try to
     make this clear when we come to that point.</p>
 </section>

 <section id="gettingitworking"><title>Getting it working</title>
     <p>Here's the basics of password protecting a directory on your
     server.</p>

     <p>You'll need to create a password file. This file should be
     placed somewhere not accessible from the web. This is so that
     folks cannot download the password file. For example, if your
     documents are served out of <code>/usr/local/apache/htdocs</code> you
     might want to put the password file(s) in
     <code>/usr/local/apache/passwd</code>.</p>

     <p>To create the file, use the <program>htpasswd</program> utility that
     came with Apache. This will be located in the <code>bin</code> directory
     of wherever you installed Apache. To create the file, type:</p>

     <example>
       htpasswd -c /usr/local/apache/passwd/passwords rbowen
     </example>

     <p><program>htpasswd</program> will ask you for the password, and
     then ask you to type it again to confirm it:</p>

     <example>
       # htpasswd -c /usr/local/apache/passwd/passwords rbowen<br />
       New password: mypassword<br />
       Re-type new password: mypassword<br />
       Adding password for user rbowen
     </example>

     <p>If <program>htpasswd</program> is not in your path, of course
     you'll have to type the full path to the file to get it to run.
     On my server, it's located at
     <code>/usr/local/apache/bin/htpasswd</code></p>

     <p>Next, you'll need to configure the server to request a
     password and tell the server which users are allowed access.
     You can do this either by editing the <code>httpd.conf</code>
     file or using an <code>.htaccess</code> file. For example, if
     you wish to protect the directory
     <code>/usr/local/apache/htdocs/secret</code>, you can use the
     following directives, either placed in the file
     <code>/usr/local/apache/htdocs/secret/.htaccess</code>, or
     placed in <code>httpd.conf</code> inside a &lt;Directory
     /usr/local/apache/apache/htdocs/secret&gt; section.</p>

     <example>
       AuthType Basic<br />
       AuthName "Restricted Files"<br />
       AuthBasicProvider file<br />
       AuthUserFile /usr/local/apache/passwd/passwords<br />
       Require user rbowen
     </example>

     <p>Let's examine each of those directives individually. The <directive
     module="core">AuthType</directive> directive selects
     that method that is used to authenticate the user. The most
     common method is <code>Basic</code>, and this is the method
     implemented by <module>mod_auth_basic</module>. It is important to be aware,
     however, that Basic authentication sends the password from the client to
     the server unencrypted. This method should therefore not be used for
     highly sensitive data. Apache supports one other authentication method:
     <code>AuthType Digest</code>. This method is implemented by <module
     >mod_auth_digest</module> and is much more secure. Only the most recent
     versions of clients are known to support Digest authentication.</p>

     <p>The <directive module="core">AuthName</directive> directive sets
     the <dfn>Realm</dfn> to be used in the authentication. The realm serves
     two major functions. First, the client often presents this information to
     the user as part of the password dialog box. Second, it is used by the
     client to determine what password to send for a given authenticated
     area.</p>

     <p>So, for example, once a client has authenticated in the
     <code>"Restricted Files"</code> area, it will automatically
     retry the same password for any area on the same server that is
     marked with the <code>"Restricted Files"</code> Realm.
     Therefore, you can prevent a user from being prompted more than
     once for a password by letting multiple restricted areas share
     the same realm. Of course, for security reasons, the client
     will always need to ask again for the password whenever the
     hostname of the server changes.</p>

     <p>The <directive module="mod_auth_basic">AuthBasicProvider</directive>
     directive registers which provider or providers will be called to handle
     the authentication processing.</p>

     <p>The <directive module="mod_authn_file">AuthUserFile</directive>
     directive sets the path to the password file that we just
     created with <program>htpasswd</program>. If you have a large number
     of users, it can be quite slow to search through a plain text
     file to authenticate the user on each request. Apache also has
     the ability to store user information in fast database files.
     The <module>mod_authn_dbm</module> module provides the <directive
     module="mod_authn_dbm">AuthDBMUserFile</directive> directive. These
     files can be created and manipulated with the <program>
     dbmmanage</program> program. Many
     other types of authentication options are available from third
     party modules in the <a
     href="http://modules.apache.org/">Apache Modules
     Database</a>.</p>

     <p>Finally, the <directive module="core">Require</directive>
     directive provides the authorization part of the process by
     setting the user that is allowed to access this region of the
     server. In the next section, we discuss various ways to use the
     <directive module="core">Require</directive> directive.</p>
 </section>

 <section id="lettingmorethanonepersonin"><title>Letting more than one
 person in</title>
     <p>The directives above only let one person (specifically
     someone with a username of <code>rbowen</code>) into the
     directory. In most cases, you'll want to let more than one
     person in. This is where the <directive module="mod_authz_groupfile"
     >AuthGroupFile</directive> comes in.</p>

     <p>If you want to let more than one person in, you'll need to
     create a group file that associates group names with a list of
     users in that group. The format of this file is pretty simple,
     and you can create it with your favorite editor. The contents
     of the file will look like this:</p>

    <example>
      GroupName: rbowen dpitts sungo rshersey
    </example>

     <p>That's just a list of the members of the group in a long
     line separated by spaces.</p>

     <p>To add a user to your already existing password file,
     type:</p>

     <example>
       htpasswd /usr/local/apache/passwd/passwords dpitts
     </example>

     <p>You'll get the same response as before, but it will be
     appended to the existing file, rather than creating a new file.
     (It's the <code>-c</code> that makes it create a new password
     file).</p>

     <p>Now, you need to modify your <code>.htaccess</code> file to
     look like the following:</p>

     <example>
       AuthType Basic<br />
       AuthName "By Invitation Only"<br />
       AuthBasicProvider file<br />
       AuthUserFile /usr/local/apache/passwd/passwords<br />
       AuthGroupFile /usr/local/apache/passwd/groups<br />
       Require group GroupName
     </example>

     <p>Now, anyone that is listed in the group <code>GroupName</code>,
     and has an entry in the <code>password</code> file, will be let in, if
     they type the correct password.</p>

     <p>There's another way to let multiple users in that is less
     specific. Rather than creating a group file, you can just use
     the following directive:</p>

     <example>
       Require valid-user
     </example>

     <p>Using that rather than the <code>Require user rbowen</code>
     line will allow anyone in that is listed in the password file,
     and who correctly enters their password. You can even emulate
     the group behavior here, by just keeping a separate password
     file for each group. The advantage of this approach is that
     Apache only has to check one file, rather than two. The
     disadvantage is that you have to maintain a bunch of password
     files, and remember to reference the right one in the
     <directive module="mod_authn_file">AuthUserFile</directive> directive.</p>
 </section>

 <section id="possibleproblems"><title>Possible problems</title>
     <p>Because of the way that Basic authentication is specified,
     your username and password must be verified every time you
     request a document from the server. This is even if you're
     reloading the same page, and for every image on the page (if
     they come from a protected directory). As you can imagine, this
     slows things down a little. The amount that it slows things
     down is proportional to the size of the password file, because
     it has to open up that file, and go down the list of users
     until it gets to your name. And it has to do this every time a
     page is loaded.</p>

     <p>A consequence of this is that there's a practical limit to
     how many users you can put in one password file. This limit
     will vary depending on the performance of your particular
     server machine, but you can expect to see slowdowns once you
     get above a few hundred entries, and may wish to consider a
     different authentication method at that time.</p>
 </section>

 <section id="whatotherneatstuffcanido"><title>What other neat stuff can I
 do?</title>
     <p>Authentication by username and password is only part of the
     story. Frequently you want to let people in based on something
     other than who they are. Something such as where they are
     coming from.</p>

     <p>The authorization providers <directive module="mod_authz_host">
     all</directive>, <directive module="mod_authz_host">
     env</directive>, <directive module="mod_authz_host">
     host</directive> and <directive module="mod_authz_host">
     ip</directive> let you allow or deny access based other host based
     criteria such as host name or ip address of te machine requesting
     a document.</p>

     <p>The usage of these providers is specified through the
     <directive module="mod_authz_core">Require</directive> and
     <directive module="mod_authz_core">Reject</directive> directives.
     These directives register the authorization providers
     that will be called during the authorization stage of the request
     processing. For example:</p>

     <example>
       Require ip <var>address</var>
     </example>

     <p>where <var>address</var> is an IP address (or a partial IP
     address) or:</p>

     <example>
       Require host <var>domain_name</var>
     </example>

     <p>where <var>domain_name</var> is a fully qualified domain name
     (or a partial domain name); you may provide multiple addresses or
     domain names, if desired.</p>

     <p>For example, if you have someone spamming your message
     board, and you want to keep them out, you could do the
     following:</p>

     <example>
       Reject ip 205.252.46.165
     </example>

     <p>Visitors coming from that address will not be able to see
     the content covered by this directive. If, instead, you have a
     machine name, rather than an IP address, you can use that.</p>

     <example>
       Reject host <var>host.example.com</var>
     </example>

     <p>And, if you'd like to block access from an entire domain,
     you can specify just part of an address or domain name:</p>

     <example>
       &lt;SatisfyAll&gt;<br />
       &nbsp;  Reject ip <var>192.101.205</var><br />
       &nbsp;  Reject host <var>cyberthugs.com</var> <var>moreidiots.com</var><br />
       &nbsp;  Reject host ke<br />
       &lt;/SatisfyAll&gt;
     </example>

     <p>Using the <directive module="mod_authz_host">Reject</directive> directive
     inside of a <directive module="mod_authz_core">&lt;SatisfyAll&gt;</directive>
     block, will let you be sure that you are actually restricting things to
     only the group that you want to let in.</p>

     <p>The above example uses the <directive module="mod_authz_core">
     &lt;SatisfyAll&gt;</directive> block to make sure that all of the
     <directive module="mod_authz_host">Reject</directive> directives are
     satisfied before granting access. The <directive module="mod_authz_core">
     &lt;SatisfyAll&gt;</directive> block as well as the
     <directive module="mod_authz_core">&lt;SatisfyOne&gt;</directive> block
     allow you to apply "AND" and "OR" logic to the authorization processing.
     For example the following authorization block would apply the logic:</p>

     <p><var>
     if ((user == "John") || <br />
     &nbsp;&nbsp;&nbsp;((Group == "admin") &amp;&amp; (ldap-group &lt;ldap-object&gt; contains auth'ed_user) &amp;&amp;<br />
     &nbsp;&nbsp;&nbsp;&nbsp;((ldap-attribute dept == "sales") ||
     (file-group contains contains auth'ed_user))))<br />
     then<br />
     &nbsp;&nbsp;auth_granted<br />
     else<br />
     &nbsp;&nbsp;auth_denied<br />
     </var></p>

     <example>
     &lt;Directory /www/mydocs&gt;<br />
     &nbsp;  Authname ...<br />
     &nbsp;  AuthBasicProvider ...<br />
     &nbsp;  ...<br />
     &nbsp;  Require user John<br />
     &nbsp;  &lt;SatisfyAll&gt;<br />
     &nbsp;&nbsp;    Require Group admins<br />
     &nbsp;&nbsp;    Require ldap-group cn=mygroup,o=foo<br />
     &nbsp;&nbsp;    &lt;SatisfyOne&gt;<br />
     &nbsp;&nbsp;&nbsp;      Require ldap-attribute dept="sales"<br />
     &nbsp;&nbsp;&nbsp;      Require file-group<br />
     &nbsp;&nbsp;    &lt;/SatisfyOne&gt;<br />
     &nbsp;  &lt;/SatisfyAll&gt;<br />
     &lt;/Directory&gt;<br />
     </example>

 </section>

 <section id="moreinformation"><title>More information</title>
     <p>You should also read the documentation for
     <module>mod_auth_basic</module> and <module>mod_authz_host</module> which
     contain some more information about how this all works.
     <module>mod_authn_alias</module> can also help in simplifying certain
     authentication configurations.</p>
 </section>

 </manualpage>
	<?xml version='1.0' encoding='UTF-8' ?>
	<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
	<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
	<!-- $LastChangedRevision$ -->

	<!--
	Copyright 2003-2005 The Apache Software Foundation or its licensors, as
	applicable.

	Licensed under the Apache License, Version 2.0 (the "License");
	you may not use this file except in compliance with the License.
	You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.
	-->

	<manualpage metafile="auth.xml.meta">
	<parentdocument href="./">How-To / Tutorials</parentdocument>

	<title>Authentication, Authorization and Access Control</title>

	<summary>
	<p>Authentication is any process by which you verify that
	someone is who they claim they are. Authorization is any
	process by which someone is allowed to be where they want to
	go, or to have information that they want to have.</p>
	</summary>

	<section id="related"><title>Related Modules and Directives</title>

	<p>There are three types of modules involved in the authentication and
	authorization process. You will usually need to choose at least one
	module from each group.</p>

	<ul>
	<li>Authentication type (see the
	<directive module="core">AuthType</directive> directive)
	<ul>
	<li><module>mod_auth_basic</module></li>
	<li><module>mod_auth_digest</module></li>
	</ul>
	</li>
	<li>Authentication provider
	<ul>
	<li><module>mod_authn_alias</module></li>
	<li><module>mod_authn_anon</module></li>
	<li><module>mod_authn_core</module></li>
	<li><module>mod_authn_dbd</module></li>
	<li><module>mod_authn_dbm</module></li>
	<li><module>mod_authn_default</module></li>
	<li><module>mod_authn_file</module></li>
	<li><module>mod_authnz_ldap</module></li>
	</ul>
	</li>
	<li>Authorization (see the
	<directive module="mod_authz_core">Require</directive> and
	<directive module="mod_authz_core">Reject</directive> directives)
	<ul>
	<li><module>mod_authnz_ldap</module></li>
	<li><module>mod_authz_core</module></li>
	<li><module>mod_authz_dbm</module></li>
	<li><module>mod_authz_default</module></li>
	<li><module>mod_authz_groupfile</module></li>
	<li><module>mod_authz_owner</module></li>
	<li><module>mod_authz_user</module></li>
	</ul>
	</li>
	</ul>

	<p>The module <module>mod_authnz_ldap</module> is both an
	authentication and authorization provider. The module
	<module>mod_authn_alias</module> is not an authentication provider
	in itself, but allows other authentication providers to be
	configured in a flexible manner.</p>

	<p>The modules <module>mod_authn_core</module> and <module>mod_authz_core
	</module> should always be loaded. These module provide the core
	directives and functionality that is common to all authentication
	and authorization providers.</p>

	</section>

	<section id="introduction"><title>Introduction</title>
	<p>If you have information on your web site that is sensitive
	or intended for only a small group of people, the techniques in
	this article will help you make sure that the people that see
	those pages are the people that you wanted to see them.</p>

	<p>This article covers the "standard" way of protecting parts
	of your web site that most of you are going to use.</p>
	</section>

	<section id="theprerequisites"><title>The Prerequisites</title>
	<p>The directives discussed in this article will need to go
	either in your main server configuration file (typically in a
	<directive module="core" type="section">Directory</directive> section), or
	in per-directory configuration files (<code>.htaccess</code> files).</p>

	<p>If you plan to use <code>.htaccess</code> files, you will
	need to have a server configuration that permits putting
	authentication directives in these files. This is done with the
	<directive module="core">AllowOverride</directive> directive, which
	specifies which directives, if any, may be put in per-directory
	configuration files.</p>

	<p>Since we're talking here about authentication, you will need
	an <directive module="core">AllowOverride</directive> directive like the
	following:</p>

	<example>
	AllowOverride AuthConfig
	</example>

	<p>Or, if you are just going to put the directives directly in
	your main server configuration file, you will of course need to
	have write permission to that file.</p>

	<p>And you'll need to know a little bit about the directory
	structure of your server, in order to know where some files are
	kept. This should not be terribly difficult, and I'll try to
	make this clear when we come to that point.</p>
	</section>

	<section id="gettingitworking"><title>Getting it working</title>
	<p>Here's the basics of password protecting a directory on your
	server.</p>

	<p>You'll need to create a password file. This file should be
	placed somewhere not accessible from the web. This is so that
	folks cannot download the password file. For example, if your
	documents are served out of <code>/usr/local/apache/htdocs</code> you
	might want to put the password file(s) in
	<code>/usr/local/apache/passwd</code>.</p>

	<p>To create the file, use the <program>htpasswd</program> utility that
	came with Apache. This will be located in the <code>bin</code> directory
	of wherever you installed Apache. To create the file, type:</p>

	<example>
	htpasswd -c /usr/local/apache/passwd/passwords rbowen
	</example>

	<p><program>htpasswd</program> will ask you for the password, and
	then ask you to type it again to confirm it:</p>

	<example>
	# htpasswd -c /usr/local/apache/passwd/passwords rbowen<br />
	New password: mypassword<br />
	Re-type new password: mypassword<br />
	Adding password for user rbowen
	</example>

	<p>If <program>htpasswd</program> is not in your path, of course
	you'll have to type the full path to the file to get it to run.
	On my server, it's located at
	<code>/usr/local/apache/bin/htpasswd</code></p>

	<p>Next, you'll need to configure the server to request a
	password and tell the server which users are allowed access.
	You can do this either by editing the <code>httpd.conf</code>
	file or using an <code>.htaccess</code> file. For example, if
	you wish to protect the directory
	<code>/usr/local/apache/htdocs/secret</code>, you can use the
	following directives, either placed in the file
	<code>/usr/local/apache/htdocs/secret/.htaccess</code>, or
	placed in <code>httpd.conf</code> inside a <Directory
	/usr/local/apache/apache/htdocs/secret> section.</p>

	<example>
	AuthType Basic<br />
	AuthName "Restricted Files"<br />
	AuthBasicProvider file<br />
	AuthUserFile /usr/local/apache/passwd/passwords<br />
	Require user rbowen
	</example>

	<p>Let's examine each of those directives individually. The <directive
	module="core">AuthType</directive> directive selects
	that method that is used to authenticate the user. The most
	common method is <code>Basic</code>, and this is the method
	implemented by <module>mod_auth_basic</module>. It is important to be aware,
	however, that Basic authentication sends the password from the client to
	the server unencrypted. This method should therefore not be used for
	highly sensitive data. Apache supports one other authentication method:
	<code>AuthType Digest</code>. This method is implemented by <module
	>mod_auth_digest</module> and is much more secure. Only the most recent
	versions of clients are known to support Digest authentication.</p>

	<p>The <directive module="core">AuthName</directive> directive sets
	the <dfn>Realm</dfn> to be used in the authentication. The realm serves
	two major functions. First, the client often presents this information to
	the user as part of the password dialog box. Second, it is used by the
	client to determine what password to send for a given authenticated
	area.</p>

	<p>So, for example, once a client has authenticated in the
	<code>"Restricted Files"</code> area, it will automatically
	retry the same password for any area on the same server that is
	marked with the <code>"Restricted Files"</code> Realm.
	Therefore, you can prevent a user from being prompted more than
	once for a password by letting multiple restricted areas share
	the same realm. Of course, for security reasons, the client
	will always need to ask again for the password whenever the
	hostname of the server changes.</p>

	<p>The <directive module="mod_auth_basic">AuthBasicProvider</directive>
	directive registers which provider or providers will be called to handle
	the authentication processing.</p>

	<p>The <directive module="mod_authn_file">AuthUserFile</directive>
	directive sets the path to the password file that we just
	created with <program>htpasswd</program>. If you have a large number
	of users, it can be quite slow to search through a plain text
	file to authenticate the user on each request. Apache also has
	the ability to store user information in fast database files.
	The <module>mod_authn_dbm</module> module provides the <directive
	module="mod_authn_dbm">AuthDBMUserFile</directive> directive. These
	files can be created and manipulated with the <program>
	dbmmanage</program> program. Many
	other types of authentication options are available from third
	party modules in the <a
	href="http://modules.apache.org/">Apache Modules
	Database</a>.</p>

	<p>Finally, the <directive module="core">Require</directive>
	directive provides the authorization part of the process by
	setting the user that is allowed to access this region of the
	server. In the next section, we discuss various ways to use the
	<directive module="core">Require</directive> directive.</p>
	</section>

	<section id="lettingmorethanonepersonin"><title>Letting more than one
	person in</title>
	<p>The directives above only let one person (specifically
	someone with a username of <code>rbowen</code>) into the
	directory. In most cases, you'll want to let more than one
	person in. This is where the <directive module="mod_authz_groupfile"
	>AuthGroupFile</directive> comes in.</p>

	<p>If you want to let more than one person in, you'll need to
	create a group file that associates group names with a list of
	users in that group. The format of this file is pretty simple,
	and you can create it with your favorite editor. The contents
	of the file will look like this:</p>

	<example>
	GroupName: rbowen dpitts sungo rshersey
	</example>

	<p>That's just a list of the members of the group in a long
	line separated by spaces.</p>

	<p>To add a user to your already existing password file,
	type:</p>

	<example>
	htpasswd /usr/local/apache/passwd/passwords dpitts
	</example>

	<p>You'll get the same response as before, but it will be
	appended to the existing file, rather than creating a new file.
	(It's the <code>-c</code> that makes it create a new password
	file).</p>

	<p>Now, you need to modify your <code>.htaccess</code> file to
	look like the following:</p>

	<example>
	AuthType Basic<br />
	AuthName "By Invitation Only"<br />
	AuthBasicProvider file<br />
	AuthUserFile /usr/local/apache/passwd/passwords<br />
	AuthGroupFile /usr/local/apache/passwd/groups<br />
	Require group GroupName
	</example>

	<p>Now, anyone that is listed in the group <code>GroupName</code>,
	and has an entry in the <code>password</code> file, will be let in, if
	they type the correct password.</p>

	<p>There's another way to let multiple users in that is less
	specific. Rather than creating a group file, you can just use
	the following directive:</p>

	<example>
	Require valid-user
	</example>

	<p>Using that rather than the <code>Require user rbowen</code>
	line will allow anyone in that is listed in the password file,
	and who correctly enters their password. You can even emulate
	the group behavior here, by just keeping a separate password
	file for each group. The advantage of this approach is that
	Apache only has to check one file, rather than two. The
	disadvantage is that you have to maintain a bunch of password
	files, and remember to reference the right one in the
	<directive module="mod_authn_file">AuthUserFile</directive> directive.</p>
	</section>

	<section id="possibleproblems"><title>Possible problems</title>
	<p>Because of the way that Basic authentication is specified,
	your username and password must be verified every time you
	request a document from the server. This is even if you're
	reloading the same page, and for every image on the page (if
	they come from a protected directory). As you can imagine, this
	slows things down a little. The amount that it slows things
	down is proportional to the size of the password file, because
	it has to open up that file, and go down the list of users
	until it gets to your name. And it has to do this every time a
	page is loaded.</p>

	<p>A consequence of this is that there's a practical limit to
	how many users you can put in one password file. This limit
	will vary depending on the performance of your particular
	server machine, but you can expect to see slowdowns once you
	get above a few hundred entries, and may wish to consider a
	different authentication method at that time.</p>
	</section>

	<section id="whatotherneatstuffcanido"><title>What other neat stuff can I
	do?</title>
	<p>Authentication by username and password is only part of the
	story. Frequently you want to let people in based on something
	other than who they are. Something such as where they are
	coming from.</p>

	<p>The authorization providers <directive module="mod_authz_host">
	all</directive>, <directive module="mod_authz_host">
	env</directive>, <directive module="mod_authz_host">
	host</directive> and <directive module="mod_authz_host">
	ip</directive> let you allow or deny access based other host based
	criteria such as host name or ip address of te machine requesting
	a document.</p>

	<p>The usage of these providers is specified through the
	<directive module="mod_authz_core">Require</directive> and
	<directive module="mod_authz_core">Reject</directive> directives.
	These directives register the authorization providers
	that will be called during the authorization stage of the request
	processing. For example:</p>

	<example>
	Require ip <var>address</var>
	</example>

	<p>where <var>address</var> is an IP address (or a partial IP
	address) or:</p>

	<example>
	Require host <var>domain_name</var>
	</example>

	<p>where <var>domain_name</var> is a fully qualified domain name
	(or a partial domain name); you may provide multiple addresses or
	domain names, if desired.</p>

	<p>For example, if you have someone spamming your message
	board, and you want to keep them out, you could do the
	following:</p>

	<example>
	Reject ip 205.252.46.165
	</example>

	<p>Visitors coming from that address will not be able to see
	the content covered by this directive. If, instead, you have a
	machine name, rather than an IP address, you can use that.</p>

	<example>
	Reject host <var>host.example.com</var>
	</example>

	<p>And, if you'd like to block access from an entire domain,
	you can specify just part of an address or domain name:</p>

	<example>
	<SatisfyAll><br />
	Reject ip <var>192.101.205</var><br />
	Reject host <var>cyberthugs.com</var> <var>moreidiots.com</var><br />
	Reject host ke<br />
	</SatisfyAll>
	</example>

	<p>Using the <directive module="mod_authz_host">Reject</directive> directive
	inside of a <directive module="mod_authz_core"><SatisfyAll></directive>
	block, will let you be sure that you are actually restricting things to
	only the group that you want to let in.</p>

	<p>The above example uses the <directive module="mod_authz_core">
	<SatisfyAll></directive> block to make sure that all of the
	<directive module="mod_authz_host">Reject</directive> directives are
	satisfied before granting access. The <directive module="mod_authz_core">
	<SatisfyAll></directive> block as well as the
	<directive module="mod_authz_core"><SatisfyOne></directive> block
	allow you to apply "AND" and "OR" logic to the authorization processing.
	For example the following authorization block would apply the logic:</p>

	<p><var>
	if ((user == "John") \|\| <br />
	((Group == "admin") && (ldap-group <ldap-object> contains auth'ed_user) &&<br />
	((ldap-attribute dept == "sales") \|\|
	(file-group contains contains auth'ed_user))))<br />
	then<br />
	auth_granted<br />
	else<br />
	auth_denied<br />
	</var></p>

	<example>
	<Directory /www/mydocs><br />
	Authname ...<br />
	AuthBasicProvider ...<br />
	...<br />
	Require user John<br />
	<SatisfyAll><br />
	Require Group admins<br />
	Require ldap-group cn=mygroup,o=foo<br />
	<SatisfyOne><br />
	Require ldap-attribute dept="sales"<br />
	Require file-group<br />
	</SatisfyOne><br />
	</SatisfyAll><br />
	</Directory><br />
	</example>

	</section>

	<section id="moreinformation"><title>More information</title>
	<p>You should also read the documentation for
	<module>mod_auth_basic</module> and <module>mod_authz_host</module> which
	contain some more information about how this all works.
	<module>mod_authn_alias</module> can also help in simplifying certain
	authentication configurations.</p>
	</section>

	</manualpage>