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