rubbos/app/httpd-2.0.64/docs/manual/howto/auth.html.en

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
   4         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   5               This file is generated from xml source: DO NOT EDIT
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7       -->
   8 <title>Authentication, Authorization and Access Control - Apache HTTP Server</title>
   9 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  10 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  11 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
  12 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
  13 <body id="manual-page"><div id="page-header">
  14 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
  15 <p class="apache">Apache HTTP Server Version 2.0</p>
  16 <img alt="" src="../images/feather.gif" /></div>
  17 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
  18 <div id="path">
  19 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.0</a> &gt; <a href="./">How-To / Tutorials</a></div><div id="page-content"><div id="preamble"><h1>Authentication, Authorization and Access Control</h1>
  20 <div class="toplang">
  21 <p><span>Available Languages: </span><a href="../en/howto/auth.html" title="English">&nbsp;en&nbsp;</a> |
  22 <a href="../es/howto/auth.html" hreflang="es" rel="alternate" title="Español">&nbsp;es&nbsp;</a> |
  23 <a href="../ja/howto/auth.html" hreflang="ja" rel="alternate" title="Japanese">&nbsp;ja&nbsp;</a> |
  24 <a href="../ko/howto/auth.html" hreflang="ko" rel="alternate" title="Korean">&nbsp;ko&nbsp;</a></p>
  25 </div>
  26
  27     <p>Authentication is any process by which you verify that
  28     someone is who they claim they are. Authorization is any
  29     process by which someone is allowed to be where they want to
  30     go, or to have information that they want to have.</p>
  31 </div>
  32 <div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#related">Related Modules and Directives</a></li>
  33 <li><img alt="" src="../images/down.gif" /> <a href="#introduction">Introduction</a></li>
  34 <li><img alt="" src="../images/down.gif" /> <a href="#theprerequisites">The Prerequisites</a></li>
  35 <li><img alt="" src="../images/down.gif" /> <a href="#gettingitworking">Getting it working</a></li>
  36 <li><img alt="" src="../images/down.gif" /> <a href="#lettingmorethanonepersonin">Letting more than one
  37 person in</a></li>
  38 <li><img alt="" src="../images/down.gif" /> <a href="#possibleproblems">Possible problems</a></li>
  39 <li><img alt="" src="../images/down.gif" /> <a href="#whatotherneatstuffcanido">What other neat stuff can I
  40 do?</a></li>
  41 <li><img alt="" src="../images/down.gif" /> <a href="#moreinformation">More information</a></li>
  42 </ul></div>
  43 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  44 <div class="section">
  45 <h2><a name="related" id="related">Related Modules and Directives</a></h2>
  46     <table class="related"><tr><th>Related Modules</th><th>Related Directives</th></tr><tr><td><ul><li><code class="module"><a href="../mod/mod_auth.html">mod_auth</a></code></li><li><code class="module"><a href="../mod/mod_access.html">mod_access</a></code></li></ul></td><td><ul><li><code class="directive"><a href="../mod/mod_access.html#allow">Allow</a></code></li><li><code class="directive"><a href="../mod/mod_auth.html#authgroupfile">AuthGroupFile</a></code></li><li><code class="directive"><a href="../mod/core.html#authname">AuthName</a></code></li><li><code class="directive"><a href="../mod/core.html#authtype">AuthType</a></code></li><li><code class="directive"><a href="../mod/mod_auth.html#authuserfile">AuthUserFile</a></code></li><li><code class="directive"><a href="../mod/mod_access.html#deny">Deny</a></code></li><li><code class="directive"><a href="../mod/core.html#options">Options</a></code></li><li><code class="directive"><a href="../mod/core.html#require">Require</a></code></li></ul></td></tr></table>
  47 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  48 <div class="section">
  49 <h2><a name="introduction" id="introduction">Introduction</a></h2>
  50     <p>If you have information on your web site that is sensitive
  51     or intended for only a small group of people, the techniques in
  52     this article will help you make sure that the people that see
  53     those pages are the people that you wanted to see them.</p>
  54
  55     <p>This article covers the "standard" way of protecting parts
  56     of your web site that most of you are going to use.</p>
  57 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  58 <div class="section">
  59 <h2><a name="theprerequisites" id="theprerequisites">The Prerequisites</a></h2>
  60     <p>The directives discussed in this article will need to go
  61     either in your main server configuration file (typically in a
  62     <code class="directive"><a href="../mod/core.html#directory">&lt;Directory&gt;</a></code> section), or
  63     in per-directory configuration files (<code>.htaccess</code> files).</p>
  64
  65     <p>If you plan to use <code>.htaccess</code> files, you will
  66     need to have a server configuration that permits putting
  67     authentication directives in these files. This is done with the
  68     <code class="directive"><a href="../mod/core.html#allowoverride">AllowOverride</a></code> directive, which
  69     specifies which directives, if any, may be put in per-directory
  70     configuration files.</p>
  71
  72     <p>Since we're talking here about authentication, you will need
  73     an <code class="directive"><a href="../mod/core.html#allowoverride">AllowOverride</a></code> directive like the
  74     following:</p>
  75
  76     <div class="example"><p><code>
  77       AllowOverride AuthConfig
  78     </code></p></div>
  79
  80     <p>Or, if you are just going to put the directives directly in
  81     your main server configuration file, you will of course need to
  82     have write permission to that file.</p>
  83
  84     <p>And you'll need to know a little bit about the directory
  85     structure of your server, in order to know where some files are
  86     kept. This should not be terribly difficult, and I'll try to
  87     make this clear when we come to that point.</p>
  88 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  89 <div class="section">
  90 <h2><a name="gettingitworking" id="gettingitworking">Getting it working</a></h2>
  91     <p>Here's the basics of password protecting a directory on your
  92     server.</p>
  93
  94     <p>You'll need to create a password file. This file should be
  95     placed somewhere not accessible from the web. This is so that
  96     folks cannot download the password file. For example, if your
  97     documents are served out of <code>/usr/local/apache/htdocs</code> you
  98     might want to put the password file(s) in
  99     <code>/usr/local/apache/passwd</code>.</p>
 100
 101     <p>To create the file, use the <code class="program"><a href="../programs/htpasswd.html">htpasswd</a></code> utility that
 102     came with Apache. This will be located in the <code>bin</code> directory
 103     of wherever you installed Apache. To create the file, type:</p>
 104
 105     <div class="example"><p><code>
 106       htpasswd -c /usr/local/apache/passwd/passwords rbowen
 107     </code></p></div>
 108
 109     <p><code class="program"><a href="../programs/htpasswd.html">htpasswd</a></code> will ask you for the password, and
 110     then ask you to type it again to confirm it:</p>
 111
 112     <div class="example"><p><code>
 113       # htpasswd -c /usr/local/apache/passwd/passwords rbowen<br />
 114       New password: mypassword<br />
 115       Re-type new password: mypassword<br />
 116       Adding password for user rbowen
 117     </code></p></div>
 118
 119     <p>If <code class="program"><a href="../programs/htpasswd.html">htpasswd</a></code> is not in your path, of course
 120     you'll have to type the full path to the file to get it to run.
 121     On my server, it's located at
 122     <code>/usr/local/apache/bin/htpasswd</code></p>
 123
 124     <p>Next, you'll need to configure the server to request a
 125     password and tell the server which users are allowed access.
 126     You can do this either by editing the <code>httpd.conf</code>
 127     file or using an <code>.htaccess</code> file. For example, if
 128     you wish to protect the directory
 129     <code>/usr/local/apache/htdocs/secret</code>, you can use the
 130     following directives, either placed in the file
 131     <code>/usr/local/apache/htdocs/secret/.htaccess</code>, or
 132     placed in <code>httpd.conf</code> inside a &lt;Directory
 133     /usr/local/apache/apache/htdocs/secret&gt; section.</p>
 134
 135     <div class="example"><p><code>
 136       AuthType Basic<br />
 137       AuthName "Restricted Files"<br />
 138       AuthUserFile /usr/local/apache/passwd/passwords<br />
 139       Require user rbowen
 140     </code></p></div>
 141
 142     <p>Let's examine each of those directives individually. The <code class="directive"><a href="../mod/core.html#authtype">AuthType</a></code> directive selects
 143     that method that is used to authenticate the user. The most
 144     common method is <code>Basic</code>, and this is the method
 145     implemented by <code class="module"><a href="../mod/mod_auth.html">mod_auth</a></code>. It is important to be aware,
 146     however, that Basic authentication sends the password from the client to
 147     the browser unencrypted. This method should therefore not be used for
 148     highly sensitive data. Apache supports one other authentication method:
 149     <code>AuthType Digest</code>. This method is implemented by <code class="module"><a href="../mod/mod_auth_digest.html">mod_auth_digest</a></code> and is much more secure. Only the most recent
 150     versions of clients are known to support Digest authentication.</p>
 151
 152     <p>The <code class="directive"><a href="../mod/core.html#authname">AuthName</a></code> directive sets
 153     the <dfn>Realm</dfn> to be used in the authentication. The realm serves
 154     two major functions. First, the client often presents this information to
 155     the user as part of the password dialog box. Second, it is used by the
 156     client to determine what password to send for a given authenticated
 157     area.</p>
 158
 159     <p>So, for example, once a client has authenticated in the
 160     <code>"Restricted Files"</code> area, it will automatically
 161     retry the same password for any area on the same server that is
 162     marked with the <code>"Restricted Files"</code> Realm.
 163     Therefore, you can prevent a user from being prompted more than
 164     once for a password by letting multiple restricted areas share
 165     the same realm. Of course, for security reasons, the client
 166     will always need to ask again for the password whenever the
 167     hostname of the server changes.</p>
 168
 169     <p>The <code class="directive"><a href="../mod/mod_auth.html#authuserfile">AuthUserFile</a></code>
 170     directive sets the path to the password file that we just
 171     created with <code class="program"><a href="../programs/htpasswd.html">htpasswd</a></code>. If you have a large number
 172     of users, it can be quite slow to search through a plain text
 173     file to authenticate the user on each request. Apache also has
 174     the ability to store user information in fast database files.
 175     The <code class="module"><a href="../mod/mod_auth_dbm.html">mod_auth_dbm</a></code> module provides the <code class="directive"><a href="../mod/mod_auth_dbm.html#authdbmuserfile">AuthDBMUserFile</a></code> directive. These
 176     files can be created and manipulated with the <code class="program"><a href="../programs/dbmmanage.html">dbmmanage</a></code> program. Many
 177     other types of authentication options are available from third
 178     party modules in the <a href="http://modules.apache.org/">Apache Modules
 179     Database</a>.</p>
 180
 181     <p>Finally, the <code class="directive"><a href="../mod/core.html#require">Require</a></code>
 182     directive provides the authorization part of the process by
 183     setting the user that is allowed to access this region of the
 184     server. In the next section, we discuss various ways to use the
 185     <code class="directive"><a href="../mod/core.html#require">Require</a></code> directive.</p>
 186 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 187 <div class="section">
 188 <h2><a name="lettingmorethanonepersonin" id="lettingmorethanonepersonin">Letting more than one
 189 person in</a></h2>
 190     <p>The directives above only let one person (specifically
 191     someone with a username of <code>rbowen</code>) into the
 192     directory. In most cases, you'll want to let more than one
 193     person in. This is where the <code class="directive"><a href="../mod/mod_auth.html#authgroupfile">AuthGroupFile</a></code> comes in.</p>
 194
 195     <p>If you want to let more than one person in, you'll need to
 196     create a group file that associates group names with a list of
 197     users in that group. The format of this file is pretty simple,
 198     and you can create it with your favorite editor. The contents
 199     of the file will look like this:</p>
 200
 201    <div class="example"><p><code>
 202      GroupName: rbowen dpitts sungo rshersey
 203    </code></p></div>
 204
 205     <p>That's just a list of the members of the group in a long
 206     line separated by spaces.</p>
 207
 208     <p>To add a user to your already existing password file,
 209     type:</p>
 210
 211     <div class="example"><p><code>
 212       htpasswd /usr/local/apache/passwd/passwords dpitts
 213     </code></p></div>
 214
 215     <p>You'll get the same response as before, but it will be
 216     appended to the existing file, rather than creating a new file.
 217     (It's the <code>-c</code> that makes it create a new password
 218     file).</p>
 219
 220     <p>Now, you need to modify your <code>.htaccess</code> file to
 221     look like the following:</p>
 222
 223     <div class="example"><p><code>
 224       AuthType Basic<br />
 225       AuthName "By Invitation Only"<br />
 226       AuthUserFile /usr/local/apache/passwd/passwords<br />
 227       AuthGroupFile /usr/local/apache/passwd/groups<br />
 228       Require group GroupName
 229     </code></p></div>
 230
 231     <p>Now, anyone that is listed in the group <code>GroupName</code>,
 232     and has an entry in the <code>password</code> file, will be let in, if
 233     they type the correct password.</p>
 234
 235     <p>There's another way to let multiple users in that is less
 236     specific. Rather than creating a group file, you can just use
 237     the following directive:</p>
 238
 239     <div class="example"><p><code>
 240       Require valid-user
 241     </code></p></div>
 242
 243     <p>Using that rather than the <code>Require user rbowen</code>
 244     line will allow anyone in that is listed in the password file,
 245     and who correctly enters their password. You can even emulate
 246     the group behavior here, by just keeping a separate password
 247     file for each group. The advantage of this approach is that
 248     Apache only has to check one file, rather than two. The
 249     disadvantage is that you have to maintain a bunch of password
 250     files, and remember to reference the right one in the
 251     <code class="directive"><a href="../mod/mod_auth.html#authuserfile">AuthUserFile</a></code> directive.</p>
 252 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 253 <div class="section">
 254 <h2><a name="possibleproblems" id="possibleproblems">Possible problems</a></h2>
 255     <p>Because of the way that Basic authentication is specified,
 256     your username and password must be verified every time you
 257     request a document from the server. This is even if you're
 258     reloading the same page, and for every image on the page (if
 259     they come from a protected directory). As you can imagine, this
 260     slows things down a little. The amount that it slows things
 261     down is proportional to the size of the password file, because
 262     it has to open up that file, and go down the list of users
 263     until it gets to your name. And it has to do this every time a
 264     page is loaded.</p>
 265
 266     <p>A consequence of this is that there's a practical limit to
 267     how many users you can put in one password file. This limit
 268     will vary depending on the performance of your particular
 269     server machine, but you can expect to see slowdowns once you
 270     get above a few hundred entries, and may wish to consider a
 271     different authentication method at that time.</p>
 272 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 273 <div class="section">
 274 <h2><a name="whatotherneatstuffcanido" id="whatotherneatstuffcanido">What other neat stuff can I
 275 do?</a></h2>
 276     <p>Authentication by username and password is only part of the
 277     story. Frequently you want to let people in based on something
 278     other than who they are. Something such as where they are
 279     coming from.</p>
 280
 281     <p>The <code class="directive"><a href="../mod/mod_access.html#allow">Allow</a></code> and
 282     <code class="directive"><a href="../mod/mod_access.html#deny">Deny</a></code> directives let
 283     you allow and deny access based on the host name, or host
 284     address, of the machine requesting a document. The
 285     <code class="directive"><a href="../mod/mod_access.html#order">Order</a></code> directive goes
 286     hand-in-hand with these two, and tells Apache in which order to
 287     apply the filters.</p>
 288
 289     <p>The usage of these directives is:</p>
 290
 291     <div class="example"><p><code>
 292       Allow from <var>address</var>
 293     </code></p></div>
 294
 295     <p>where <var>address</var> is an IP address (or a partial IP
 296     address) or a fully qualified domain name (or a partial domain
 297     name); you may provide multiple addresses or domain names, if
 298     desired.</p>
 299
 300     <p>For example, if you have someone spamming your message
 301     board, and you want to keep them out, you could do the
 302     following:</p>
 303
 304     <div class="example"><p><code>
 305       Deny from 10.252.46.165
 306     </code></p></div>
 307
 308     <p>Visitors coming from that address will not be able to see
 309     the content covered by this directive. If, instead, you have a
 310     machine name, rather than an IP address, you can use that.</p>
 311
 312     <div class="example"><p><code>
 313       Deny from <var>host.example.com</var>
 314     </code></p></div>
 315
 316     <p>And, if you'd like to block access from an entire domain,
 317     you can specify just part of an address or domain name:</p>
 318
 319     <div class="example"><p><code>
 320       Deny from <var>192.168.205</var><br />
 321       Deny from <var>phishers.example.com</var> <var>moreidiots.example</var><br />
 322       Deny from ke
 323     </code></p></div>
 324
 325     <p>Using <code class="directive"><a href="../mod/mod_access.html#order">Order</a></code> will let you be
 326     sure that you are actually restricting things to the group that you want
 327     to let in, by combining a <code class="directive"><a href="../mod/mod_access.html#deny">Deny</a></code>
 328     and an <code class="directive"><a href="../mod/mod_access.html#allow">Allow</a></code> directive:</p>
 329
 330     <div class="example"><p><code>
 331       Order deny,allow<br />
 332       Deny from all<br />
 333       Allow from <var>dev.example.com</var>
 334     </code></p></div>
 335
 336     <p>Listing just the <code class="directive"><a href="../mod/mod_access.html#allow">Allow</a></code>
 337     directive would not do what you want, because it will let folks from that
 338     host in, in addition to letting everyone in. What you want is to let
 339     <em>only</em> those folks in.</p>
 340 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 341 <div class="section">
 342 <h2><a name="moreinformation" id="moreinformation">More information</a></h2>
 343     <p>You should also read the documentation for <code class="module"><a href="../mod/mod_auth.html">mod_auth</a></code>
 344     and <code class="module"><a href="../mod/mod_access.html">mod_access</a></code> which contain some more information
 345     about how this all works.</p>
 346 </div></div>
 347 <div class="bottomlang">
 348 <p><span>Available Languages: </span><a href="../en/howto/auth.html" title="English">&nbsp;en&nbsp;</a> |
 349 <a href="../es/howto/auth.html" hreflang="es" rel="alternate" title="Español">&nbsp;es&nbsp;</a> |
 350 <a href="../ja/howto/auth.html" hreflang="ja" rel="alternate" title="Japanese">&nbsp;ja&nbsp;</a> |
 351 <a href="../ko/howto/auth.html" hreflang="ko" rel="alternate" title="Korean">&nbsp;ko&nbsp;</a></p>
 352 </div><div id="footer">
 353 <p class="apache">Copyright 2009 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
 354 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>
 355 </body></html>