1 <?xml version='1.0' encoding='UTF-8' ?>
2 <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
4 <!-- $LastChangedRevision$ -->
7 Copyright 2003-2005 The Apache Software Foundation or its licensors, as
10 Licensed under the Apache License, Version 2.0 (the "License");
11 you may not use this file except in compliance with the License.
12 You may obtain a copy of the License at
14 http://www.apache.org/licenses/LICENSE-2.0
16 Unless required by applicable law or agreed to in writing, software
17 distributed under the License is distributed on an "AS IS" BASIS,
18 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19 See the License for the specific language governing permissions and
20 limitations under the License.
23 <manualpage metafile="auth.xml.meta">
24 <parentdocument href="./">How-To / Tutorials</parentdocument>
26 <title>Authentication, Authorization and Access Control</title>
29 <p>Authentication is any process by which you verify that
30 someone is who they claim they are. Authorization is any
31 process by which someone is allowed to be where they want to
32 go, or to have information that they want to have.</p>
35 <section id="related"><title>Related Modules and Directives</title>
37 <p>There are three types of modules involved in the authentication and
38 authorization process. You will usually need to choose at least one
39 module from each group.</p>
42 <li>Authentication type (see the
43 <directive module="core">AuthType</directive> directive)
45 <li><module>mod_auth_basic</module></li>
46 <li><module>mod_auth_digest</module></li>
49 <li>Authentication provider (see the
50 <directive module="mod_auth_basic">AuthBasicProvider</directive> and
51 <directive module="mod_auth_digest">AuthDigestProvider</directive> directives)
54 <li><module>mod_authn_anon</module></li>
55 <li><module>mod_authn_dbd</module></li>
56 <li><module>mod_authn_dbm</module></li>
57 <li><module>mod_authn_default</module></li>
58 <li><module>mod_authn_file</module></li>
59 <li><module>mod_authnz_ldap</module></li>
62 <li>Authorization (see the
63 <directive module="core">Require</directive> directive)
65 <li><module>mod_authnz_ldap</module></li>
66 <li><module>mod_authz_dbm</module></li>
67 <li><module>mod_authz_dbm</module></li>
68 <li><module>mod_authz_default</module></li>
69 <li><module>mod_authz_groupfile</module></li>
70 <li><module>mod_authz_host</module></li>
71 <li><module>mod_authz_owner</module></li>
72 <li><module>mod_authz_user</module></li>
77 <p>In addition to these modules, there are also
78 <module>mod_authn_core</module> and
79 <module>mod_authz_core</module>. These module implement core
80 directives that are core to all auth modules.</p>
82 <p>The module <module>mod_authnz_ldap</module> is both an
83 authentication and authorization provider. The module
84 <module>mod_authz_host</module> provides authorization
85 and access control based on hostname, IP address or characteristics
86 of the request, but is not part of the authentication provider
87 system. For backwards compatibility with the mod_access, there is
88 a new module <module>mod_access_compat</module>.</p>
90 <p>You probably also want to take a look at the <a
91 href="access.html">Access Control</a> howto, which discusses the
92 various ways to control access to your server.</p>
96 <section id="introduction"><title>Introduction</title>
97 <p>If you have information on your web site that is sensitive
98 or intended for only a small group of people, the techniques in
99 this article will help you make sure that the people that see
100 those pages are the people that you wanted to see them.</p>
102 <p>This article covers the "standard" way of protecting parts
103 of your web site that most of you are going to use.</p>
105 <note><title>Note:</title>
106 <p>If your data really needs to be secure, consider using
107 <module>mod_ssl</module> in addition to any authentication.</p>
111 <section id="theprerequisites"><title>The Prerequisites</title>
112 <p>The directives discussed in this article will need to go
113 either in your main server configuration file (typically in a
114 <directive module="core" type="section">Directory</directive> section), or
115 in per-directory configuration files (<code>.htaccess</code> files).</p>
117 <p>If you plan to use <code>.htaccess</code> files, you will
118 need to have a server configuration that permits putting
119 authentication directives in these files. This is done with the
120 <directive module="core">AllowOverride</directive> directive, which
121 specifies which directives, if any, may be put in per-directory
122 configuration files.</p>
124 <p>Since we're talking here about authentication, you will need
125 an <directive module="core">AllowOverride</directive> directive like the
129 AllowOverride AuthConfig
132 <p>Or, if you are just going to put the directives directly in
133 your main server configuration file, you will of course need to
134 have write permission to that file.</p>
136 <p>And you'll need to know a little bit about the directory
137 structure of your server, in order to know where some files are
138 kept. This should not be terribly difficult, and I'll try to
139 make this clear when we come to that point.</p>
141 <p>You will also need to make sure that the modules
142 <module>mod_authn_core</module> and <module>mod_authz_core</module>
143 have either been built into the httpd binary or loaded by the
144 httpd.conf configuration file. Both of these modules provide core
145 directives and functionality that are critical to the configuration
146 and use of authentication and authorization in the web server.</p>
149 <section id="gettingitworking"><title>Getting it working</title>
150 <p>Here's the basics of password protecting a directory on your
153 <p>First, you need to create a password file. Exactly how you do
154 this will vary depending on what authentication provider you have
155 chosen. More on that later. To start with, we'll use a text password
158 <p>This file should be
159 placed somewhere not accessible from the web. This is so that
160 folks cannot download the password file. For example, if your
161 documents are served out of <code>/usr/local/apache/htdocs</code> you
162 might want to put the password file(s) in
163 <code>/usr/local/apache/passwd</code>.</p>
165 <p>To create the file, use the <program>htpasswd</program> utility that
166 came with Apache. This will be located in the <code>bin</code> directory
167 of wherever you installed Apache. If you have installed Apache from
168 a third-party package, it may be in your execution path.</p>
170 <p>To create the file, type:</p>
173 htpasswd -c /usr/local/apache/passwd/passwords rbowen
176 <p><program>htpasswd</program> will ask you for the password, and
177 then ask you to type it again to confirm it:</p>
180 # htpasswd -c /usr/local/apache/passwd/passwords rbowen<br />
181 New password: mypassword<br />
182 Re-type new password: mypassword<br />
183 Adding password for user rbowen
186 <p>If <program>htpasswd</program> is not in your path, of course
187 you'll have to type the full path to the file to get it to run.
188 With a default installation, it's located at
189 <code>/usr/local/apache2/bin/htpasswd</code></p>
191 <p>Next, you'll need to configure the server to request a
192 password and tell the server which users are allowed access.
193 You can do this either by editing the <code>httpd.conf</code>
194 file or using an <code>.htaccess</code> file. For example, if
195 you wish to protect the directory
196 <code>/usr/local/apache/htdocs/secret</code>, you can use the
197 following directives, either placed in the file
198 <code>/usr/local/apache/htdocs/secret/.htaccess</code>, or
199 placed in <code>httpd.conf</code> inside a <Directory
200 /usr/local/apache/apache/htdocs/secret> section.</p>
204 AuthName "Restricted Files"<br />
205 # (Following line optional)<br />
206 AuthBasicProvider file<br />
207 AuthUserFile /usr/local/apache/passwd/passwords<br />
211 <p>Let's examine each of those directives individually. The <directive
212 module="core">AuthType</directive> directive selects
213 that method that is used to authenticate the user. The most
214 common method is <code>Basic</code>, and this is the method
215 implemented by <module>mod_auth_basic</module>. It is important to be aware,
216 however, that Basic authentication sends the password from the client to
217 the server unencrypted. This method should therefore not be used for
218 highly sensitive data, unless accompanied by <module>mod_ssl</module>.
219 Apache supports one other authentication method:
220 <code>AuthType Digest</code>. This method is implemented by <module
221 >mod_auth_digest</module> and is much more secure. Most recent
222 browsers support Digest authentication.</p>
224 <p>The <directive module="core">AuthName</directive> directive sets
225 the <dfn>Realm</dfn> to be used in the authentication. The realm serves
226 two major functions. First, the client often presents this information to
227 the user as part of the password dialog box. Second, it is used by the
228 client to determine what password to send for a given authenticated
231 <p>So, for example, once a client has authenticated in the
232 <code>"Restricted Files"</code> area, it will automatically
233 retry the same password for any area on the same server that is
234 marked with the <code>"Restricted Files"</code> Realm.
235 Therefore, you can prevent a user from being prompted more than
236 once for a password by letting multiple restricted areas share
237 the same realm. Of course, for security reasons, the client
238 will always need to ask again for the password whenever the
239 hostname of the server changes.</p>
242 module="mod_auth_basic">AuthBasicProvider</directive> is,
243 in this case, optional, since <code>file</code> is the default value
244 for this directive. You'll need to use this directive if you are
245 choosing a different source for authentication, such as
246 <module>mod_authn_dbm</module> or <module>mod_authn_dbd</module>.</p>
248 <p>The <directive module="mod_authn_file">AuthUserFile</directive>
249 directive sets the path to the password file that we just
250 created with <program>htpasswd</program>. If you have a large number
251 of users, it can be quite slow to search through a plain text
252 file to authenticate the user on each request. Apache also has
253 the ability to store user information in fast database files.
254 The <module>mod_authn_dbm</module> module provides the <directive
255 module="mod_authn_dbm">AuthDBMUserFile</directive> directive. These
256 files can be created and manipulated with the <program>
257 dbmmanage</program> program. Many
258 other types of authentication options are available from third
259 party modules in the <a
260 href="http://modules.apache.org/">Apache Modules
263 <p>Finally, the <directive module="core">Require</directive>
264 directive provides the authorization part of the process by
265 setting the user that is allowed to access this region of the
266 server. In the next section, we discuss various ways to use the
267 <directive module="core">Require</directive> directive.</p>
270 <section id="lettingmorethanonepersonin"><title>Letting more than one
272 <p>The directives above only let one person (specifically
273 someone with a username of <code>rbowen</code>) into the
274 directory. In most cases, you'll want to let more than one
275 person in. This is where the <directive module="mod_authz_groupfile"
276 >AuthGroupFile</directive> comes in.</p>
278 <p>If you want to let more than one person in, you'll need to
279 create a group file that associates group names with a list of
280 users in that group. The format of this file is pretty simple,
281 and you can create it with your favorite editor. The contents
282 of the file will look like this:</p>
285 GroupName: rbowen dpitts sungo rshersey
288 <p>That's just a list of the members of the group in a long
289 line separated by spaces.</p>
291 <p>To add a user to your already existing password file,
295 htpasswd /usr/local/apache/passwd/passwords dpitts
298 <p>You'll get the same response as before, but it will be
299 appended to the existing file, rather than creating a new file.
300 (It's the <code>-c</code> that makes it create a new password
303 <p>Now, you need to modify your <code>.htaccess</code> file to
304 look like the following:</p>
308 AuthName "By Invitation Only"<br />
310 AuthBasicProvider file
311 AuthUserFile /usr/local/apache/passwd/passwords<br />
312 AuthGroupFile /usr/local/apache/passwd/groups<br />
313 Require group GroupName
316 <p>Now, anyone that is listed in the group <code>GroupName</code>,
317 and has an entry in the <code>password</code> file, will be let in, if
318 they type the correct password.</p>
320 <p>There's another way to let multiple users in that is less
321 specific. Rather than creating a group file, you can just use
322 the following directive:</p>
328 <p>Using that rather than the <code>Require user rbowen</code>
329 line will allow anyone in that is listed in the password file,
330 and who correctly enters their password. You can even emulate
331 the group behavior here, by just keeping a separate password
332 file for each group. The advantage of this approach is that
333 Apache only has to check one file, rather than two. The
334 disadvantage is that you have to maintain a bunch of password
335 files, and remember to reference the right one in the
336 <directive module="mod_authn_file">AuthUserFile</directive> directive.</p>
339 <section id="possibleproblems"><title>Possible problems</title>
340 <p>Because of the way that Basic authentication is specified,
341 your username and password must be verified every time you
342 request a document from the server. This is even if you're
343 reloading the same page, and for every image on the page (if
344 they come from a protected directory). As you can imagine, this
345 slows things down a little. The amount that it slows things
346 down is proportional to the size of the password file, because
347 it has to open up that file, and go down the list of users
348 until it gets to your name. And it has to do this every time a
351 <p>A consequence of this is that there's a practical limit to
352 how many users you can put in one password file. This limit
353 will vary depending on the performance of your particular
354 server machine, but you can expect to see slowdowns once you
355 get above a few hundred entries, and may wish to consider a
356 different authentication method at that time.</p>
359 <section id="dbmdbd"><title>Alternate password storage</title>
361 <p>Because storing passwords in plain text files has the above
362 problems, you may wish to store your passwords somewhere else, such
363 as in a database.</p>
365 <p><module>mod_authn_dbm</module> and <module>mod_authn_dbd</module>
366 are two modules which make this possible. Rather than selecting
367 <directive module="mod_auth_basic">AuthBasicSource</directive> file,
368 instead you can choose <code>dbm</code> or <code>dbd</code> as your
371 <p>To select a dbd file rather than a text file, for example:</p>
374 <Directory /www/docs/private><br />
375 AuthName "Private"<br />
377 AuthBasicProvider dbm<br />
378 AuthDBMUserFile /www/passwords/passwd.dbm<br />
382 <p>Other options are available. Consult the
383 <module>mod_authn_dbm</module> documentation for more details.</p>
386 <section id="multprovider"><title>Using multiple providers</title>
388 <p>With the introduction of the new provider based authentication and
389 authorization architecture, you are no longer locked into a single
390 authentication or authorization method. In fact any number of the
391 providers can be mixed and matched to provide you with exactly the
392 scheme that meets your needs. In the following example, both the
393 file and ldap based authentication providers are being used.</p>
396 <Directory /www/docs/private><br />
397 AuthName "Private"<br />
399 AuthBasicProvider file ldap<br />
400 AuthUserFile /usr/local/apache/passwd/passwords<br />
401 AuthLDAPURL ldap://ldaphost/o=yourorg<br />
405 <p>In this example the file provider will attempt to authenticate
406 the user first. If it is unable to authenticate the user, the ldap
407 provider will be called. This allows the scope of authentication
408 to be broadened if your organization implements more than
409 one type of authentication store. Other authentication and authorization
410 scenarios may include mixing one type of authentication with a
411 different type of authorization. For example, authenticating against
412 a password file yet authorizing against and ldap directory.</p>
414 <p>Just as multiple authentication providers can be implemented, multiple
415 authorization methods can also be used. In this example both file group
416 authorization as well as ldap group authorization is being used.</p>
419 <Directory /www/docs/private><br />
420 AuthName "Private"<br />
422 AuthBasicProvider file<br />
423 AuthUserFile /usr/local/apache/passwd/passwords<br />
424 AuthLDAPURL ldap://ldaphost/o=yourorg
425 AuthGroupFile /usr/local/apache/passwd/groups<br />
426 Require group GroupName<br />
427 Require ldap-group cn=mygroup,o=yourorg
430 <p>To take authorization a little further, the directives
431 <directive module="mod_authz_core"><SatisfyAll></directive> and
432 <directive module="mod_authz_core"><SatisfyOne></directive> allow
433 AND/OR logic to be applied so that the order in which authorization
434 is handled can be completely controled through the configuration. See
435 these directives for a complete example on they can be applied.</p>
439 <section id="multprovider"><title>Beyond just authorization</title>
441 <p>The way that authorization can be apply is now much more flexible
442 than just a single check against a single data store. Ordering, logic
443 and choosing how authorization will be done is now possible.</p>
445 <section id="authandororder"><title>Applying AND/OR logic and ordering</title>
446 <p>Controling how and in what order authorization will be applied
447 has been a bit of a mystery in the past. In Apache 2.2 a provider based
448 authentication mechanism was introduced to decouple the actual
449 authentication process from authorization and supporting functionality.
450 One of the side benefits was that authentication providers could be
451 configured and called in a specific order which didn't depend on the
452 load order of the auth module itself. This same provider based mechanism
453 has been brought forward into authorization as well. What this means is
454 that the <directive module="mod_authz_core">Require</directive> directive
455 not only specifies which authorization methods should be used, it also
456 specifies the order in which they are called. Multiple autorization
457 methods are called in the same order in which the
458 <directive module="mod_authz_core">Require</directive> directives appear
459 in the configuration.</p>
461 <p>With the introduction of the directives
462 <directive module="mod_authz_core"><SatisfyAll></directive> and
463 <directive module="mod_authz_core"><SatisfyOne></directive>, the
464 configuration also has control over when the
465 authorization methods are called and what criteria determines when
466 access is granted. For example the following authorization block would
470 if ((user == "John") || <br />
471 ((Group == "admin") && (ldap-group <ldap-object> contains auth'ed_user) &&<br />
472 ((ldap-attribute dept == "sales") ||
473 (file-group contains contains auth'ed_user))))<br />
475 auth_granted<br />
477 auth_denied<br />
481 <Directory /www/mydocs><br />
482 Authname ...<br />
483 AuthBasicProvider ...<br />
485 Require user John<br />
486 <SatisfyAll><br />
487 Require Group admins<br />
488 Require ldap-group cn=mygroup,o=foo<br />
489 <SatisfyOne><br />
490 Require ldap-attribute dept="sales"<br />
491 Require file-group<br />
492 </SatisfyOne><br />
493 </SatisfyAll><br />
494 </Directory><br />
497 <p>By default all <directive module="mod_authz_core">Require</directive>
498 directives are handled through and OR operation. In other words, if
499 any of the specified authorization methods succeed, then authorization
500 is granted. By enclosing a set of
501 <directive module="mod_authz_core">Require</directive> directives within
502 a <directive module="mod_authz_core"><SatisfyAll></directive> block,
503 the processing switches to an AND operation which requires all authorization
504 methods to succeed before authorization is granted.</p>
508 <section id="reqaccessctrl"><title>Using 'Require' or 'Reject' for access control</title>
509 <p>Authentication by username and password is only part of the
510 story. Frequently you want to let people in based on something
511 other than who they are. Something such as where they are
514 <p>The authorization providers <directive module="mod_authz_host">
515 all</directive>, <directive module="mod_authz_host">
516 env</directive>, <directive module="mod_authz_host">
517 host</directive> and <directive module="mod_authz_host">
518 ip</directive> let you allow or deny access based other host based
519 criteria such as host name or ip address of the machine requesting
522 <p>The usage of these providers is specified through the
523 <directive module="mod_authz_core">Require</directive> and
524 <directive module="mod_authz_core">Reject</directive> directives.
525 These directives register the authorization providers
526 that will be called during the authorization stage of the request
527 processing. For example:</p>
530 Require ip <var>address</var>
533 <p>where <var>address</var> is an IP address (or a partial IP
537 Require host <var>domain_name</var>
540 <p>where <var>domain_name</var> is a fully qualified domain name
541 (or a partial domain name); you may provide multiple addresses or
542 domain names, if desired.</p>
544 <p>For example, if you have someone spamming your message
545 board, and you want to keep them out, you could do the
549 Reject ip 205.252.46.165
552 <p>Visitors coming from that address will not be able to see
553 the content covered by this directive. If, instead, you have a
554 machine name, rather than an IP address, you can use that.</p>
557 Reject host <var>host.example.com</var>
560 <p>And, if you'd like to block access from an entire domain,
561 you can specify just part of an address or domain name:</p>
564 <SatisfyAll><br />
565 Reject ip <var>192.101.205</var><br />
566 Reject host <var>cyberthugs.com</var> <var>moreidiots.com</var><br />
567 Reject host ke<br />
571 <p>Using the <directive module="mod_authz_host">Reject</directive> directive
572 inside of a <directive module="mod_authz_core"><SatisfyAll></directive>
573 block, will let you be sure that you are actually restricting things to
574 only the group that you want to let in.</p>
576 <p>The above example uses the <directive module="mod_authz_core">
577 <SatisfyAll></directive> block to make sure that all of the
578 <directive module="mod_authz_host">Reject</directive> directives are
579 satisfied before granting access. </p>
583 <section id="filesystem"><title>Access Control backwards compatibility</title>
584 <p>One of the side effects of adopting a provider based mechanism for
585 authentication is that the need for the previous access control directives
586 <directive module="mod_access_compat">Order</directive>,
587 <directive module="mod_access_compat">Allow</directive>,
588 <directive module="mod_access_compat">Deny</directive> and
589 <directive module="mod_access_compat">Satisfy</directive> are no longer needed.
590 However to provide backwards compatibility for older configurations, these
591 directives have been moved to the <module>mod_access_compat</module> module.</p>
593 <p>One of the problems with these directives was that the line between
594 authorization and access control was very fuzzy. The
595 <directive module="mod_access_compat">Satisfy</directive> directive
596 tried to tie these two stages together by hooking itself into the
597 request processing itself. Now that these directive have been moved to the
598 <module>mod_access_compat</module>, mixing the new authorization directives
599 with the older access control directives becomes difficult. To address this
600 issue, the <module>mod_authz_default</module> module becomes very important and must
601 be loaded. The main purpose of the <module>mod_authz_default</module> module is
602 to handle any authorization requests that could not be handled by the
603 authorization providers. But when the older access control directives are used,
604 it also links access control with authorization and determines if access
605 should be granted based on the outcome of each stage. Therefore if the
606 older directives do not seem to be working properly, it might be because the
607 <module>mod_authz_default</module> module has not been loaded.</p>
613 <section id="moreinformation"><title>More information</title>
614 <p>You should also read the documentation for
615 <module>mod_auth_basic</module> and <module>mod_authz_host</module> which
616 contain some more information about how this all works.
617 The directive <directive module="mod_authn_core"><AuthnProviderAlias></directive>
618 can also help in simplifying certain authentication configurations.</p>
620 <p>And you may want to look at the <a href="access.html">Access
621 Control</a> howto, which discusses a number of related topics.</p>