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 Licensed to the Apache Software Foundation (ASF) under one or more
8 contributor license agreements. See the NOTICE file distributed with
9 this work for additional information regarding copyright ownership.
10 The ASF licenses this file to You under the Apache License, Version 2.0
11 (the "License"); you may not use this file except in compliance with
12 the License. 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="mod_authn_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_file</module></li>
58 <li><module>mod_authnz_ldap</module></li>
61 <li>Authorization (see the
62 <directive module="mod_authz_core">Require</directive> directive)
64 <li><module>mod_authnz_ldap</module></li>
65 <li><module>mod_authz_dbd</module></li>
66 <li><module>mod_authz_dbm</module></li>
67 <li><module>mod_authz_groupfile</module></li>
68 <li><module>mod_authz_host</module></li>
69 <li><module>mod_authz_owner</module></li>
70 <li><module>mod_authz_user</module></li>
75 <p>In addition to these modules, there are also
76 <module>mod_authn_core</module> and
77 <module>mod_authz_core</module>. These module implement core
78 directives that are core to all auth modules.</p>
80 <p>The module <module>mod_authnz_ldap</module> is both an
81 authentication and authorization provider. The module
82 <module>mod_authz_host</module> provides authorization
83 and access control based on hostname, IP address or characteristics
84 of the request, but is not part of the authentication provider
85 system. For backwards compatibility with the mod_access, there is
86 a new module <module>mod_access_compat</module>.</p>
88 <p>You probably also want to take a look at the <a
89 href="access.html">Access Control</a> howto, which discusses the
90 various ways to control access to your server.</p>
94 <section id="introduction"><title>Introduction</title>
95 <p>If you have information on your web site that is sensitive
96 or intended for only a small group of people, the techniques in
97 this article will help you make sure that the people that see
98 those pages are the people that you wanted to see them.</p>
100 <p>This article covers the "standard" way of protecting parts
101 of your web site that most of you are going to use.</p>
103 <note><title>Note:</title>
104 <p>If your data really needs to be secure, consider using
105 <module>mod_ssl</module> in addition to any authentication.</p>
109 <section id="theprerequisites"><title>The Prerequisites</title>
110 <p>The directives discussed in this article will need to go
111 either in your main server configuration file (typically in a
112 <directive module="core" type="section">Directory</directive> section), or
113 in per-directory configuration files (<code>.htaccess</code> files).</p>
115 <p>If you plan to use <code>.htaccess</code> files, you will
116 need to have a server configuration that permits putting
117 authentication directives in these files. This is done with the
118 <directive module="core">AllowOverride</directive> directive, which
119 specifies which directives, if any, may be put in per-directory
120 configuration files.</p>
122 <p>Since we're talking here about authentication, you will need
123 an <directive module="core">AllowOverride</directive> directive like the
127 AllowOverride AuthConfig
130 <p>Or, if you are just going to put the directives directly in
131 your main server configuration file, you will of course need to
132 have write permission to that file.</p>
134 <p>And you'll need to know a little bit about the directory
135 structure of your server, in order to know where some files are
136 kept. This should not be terribly difficult, and I'll try to
137 make this clear when we come to that point.</p>
139 <p>You will also need to make sure that the modules
140 <module>mod_authn_core</module> and <module>mod_authz_core</module>
141 have either been built into the httpd binary or loaded by the
142 httpd.conf configuration file. Both of these modules provide core
143 directives and functionality that are critical to the configuration
144 and use of authentication and authorization in the web server.</p>
147 <section id="gettingitworking"><title>Getting it working</title>
148 <p>Here's the basics of password protecting a directory on your
151 <p>First, you need to create a password file. Exactly how you do
152 this will vary depending on what authentication provider you have
153 chosen. More on that later. To start with, we'll use a text password
156 <p>This file should be
157 placed somewhere not accessible from the web. This is so that
158 folks cannot download the password file. For example, if your
159 documents are served out of <code>/usr/local/apache/htdocs</code> you
160 might want to put the password file(s) in
161 <code>/usr/local/apache/passwd</code>.</p>
163 <p>To create the file, use the <program>htpasswd</program> utility that
164 came with Apache. This will be located in the <code>bin</code> directory
165 of wherever you installed Apache. If you have installed Apache from
166 a third-party package, it may be in your execution path.</p>
168 <p>To create the file, type:</p>
171 htpasswd -c /usr/local/apache/passwd/passwords rbowen
174 <p><program>htpasswd</program> will ask you for the password, and
175 then ask you to type it again to confirm it:</p>
178 # htpasswd -c /usr/local/apache/passwd/passwords rbowen<br />
179 New password: mypassword<br />
180 Re-type new password: mypassword<br />
181 Adding password for user rbowen
184 <p>If <program>htpasswd</program> is not in your path, of course
185 you'll have to type the full path to the file to get it to run.
186 With a default installation, it's located at
187 <code>/usr/local/apache2/bin/htpasswd</code></p>
189 <p>Next, you'll need to configure the server to request a
190 password and tell the server which users are allowed access.
191 You can do this either by editing the <code>httpd.conf</code>
192 file or using an <code>.htaccess</code> file. For example, if
193 you wish to protect the directory
194 <code>/usr/local/apache/htdocs/secret</code>, you can use the
195 following directives, either placed in the file
196 <code>/usr/local/apache/htdocs/secret/.htaccess</code>, or
197 placed in <code>httpd.conf</code> inside a <Directory
198 /usr/local/apache/htdocs/secret> section.</p>
202 AuthName "Restricted Files"<br />
203 # (Following line optional)<br />
204 AuthBasicProvider file<br />
205 AuthUserFile /usr/local/apache/passwd/passwords<br />
209 <p>Let's examine each of those directives individually. The <directive
210 module="mod_authn_core">AuthType</directive> directive selects
211 that method that is used to authenticate the user. The most
212 common method is <code>Basic</code>, and this is the method
213 implemented by <module>mod_auth_basic</module>. It is important to be aware,
214 however, that Basic authentication sends the password from the client to
215 the server unencrypted. This method should therefore not be used for
216 highly sensitive data, unless accompanied by <module>mod_ssl</module>.
217 Apache supports one other authentication method:
218 <code>AuthType Digest</code>. This method is implemented by <module
219 >mod_auth_digest</module> and is much more secure. Most recent
220 browsers support Digest authentication.</p>
222 <p>The <directive module="mod_authn_core">AuthName</directive> directive sets
223 the <dfn>Realm</dfn> to be used in the authentication. The realm serves
224 two major functions. First, the client often presents this information to
225 the user as part of the password dialog box. Second, it is used by the
226 client to determine what password to send for a given authenticated
229 <p>So, for example, once a client has authenticated in the
230 <code>"Restricted Files"</code> area, it will automatically
231 retry the same password for any area on the same server that is
232 marked with the <code>"Restricted Files"</code> Realm.
233 Therefore, you can prevent a user from being prompted more than
234 once for a password by letting multiple restricted areas share
235 the same realm. Of course, for security reasons, the client
236 will always need to ask again for the password whenever the
237 hostname of the server changes.</p>
240 module="mod_auth_basic">AuthBasicProvider</directive> is,
241 in this case, optional, since <code>file</code> is the default value
242 for this directive. You'll need to use this directive if you are
243 choosing a different source for authentication, such as
244 <module>mod_authn_dbm</module> or <module>mod_authn_dbd</module>.</p>
246 <p>The <directive module="mod_authn_file">AuthUserFile</directive>
247 directive sets the path to the password file that we just
248 created with <program>htpasswd</program>. If you have a large number
249 of users, it can be quite slow to search through a plain text
250 file to authenticate the user on each request. Apache also has
251 the ability to store user information in fast database files.
252 The <module>mod_authn_dbm</module> module provides the <directive
253 module="mod_authn_dbm">AuthDBMUserFile</directive> directive. These
254 files can be created and manipulated with the <program>
255 dbmmanage</program> program. Many
256 other types of authentication options are available from third
257 party modules in the <a
258 href="http://modules.apache.org/">Apache Modules
261 <p>Finally, the <directive module="mod_authz_core">Require</directive>
262 directive provides the authorization part of the process by
263 setting the user that is allowed to access this region of the
264 server. In the next section, we discuss various ways to use the
265 <directive module="mod_authz_core">Require</directive> directive.</p>
268 <section id="lettingmorethanonepersonin"><title>Letting more than one
270 <p>The directives above only let one person (specifically
271 someone with a username of <code>rbowen</code>) into the
272 directory. In most cases, you'll want to let more than one
273 person in. This is where the <directive module="mod_authz_groupfile"
274 >AuthGroupFile</directive> comes in.</p>
276 <p>If you want to let more than one person in, you'll need to
277 create a group file that associates group names with a list of
278 users in that group. The format of this file is pretty simple,
279 and you can create it with your favorite editor. The contents
280 of the file will look like this:</p>
283 GroupName: rbowen dpitts sungo rshersey
286 <p>That's just a list of the members of the group in a long
287 line separated by spaces.</p>
289 <p>To add a user to your already existing password file,
293 htpasswd /usr/local/apache/passwd/passwords dpitts
296 <p>You'll get the same response as before, but it will be
297 appended to the existing file, rather than creating a new file.
298 (It's the <code>-c</code> that makes it create a new password
301 <p>Now, you need to modify your <code>.htaccess</code> file to
302 look like the following:</p>
306 AuthName "By Invitation Only"<br />
307 # Optional line:<br />
308 AuthBasicProvider file<br />
309 AuthUserFile /usr/local/apache/passwd/passwords<br />
310 AuthGroupFile /usr/local/apache/passwd/groups<br />
311 Require group GroupName
314 <p>Now, anyone that is listed in the group <code>GroupName</code>,
315 and has an entry in the <code>password</code> file, will be let in, if
316 they type the correct password.</p>
318 <p>There's another way to let multiple users in that is less
319 specific. Rather than creating a group file, you can just use
320 the following directive:</p>
326 <p>Using that rather than the <code>Require user rbowen</code>
327 line will allow anyone in that is listed in the password file,
328 and who correctly enters their password. You can even emulate
329 the group behavior here, by just keeping a separate password
330 file for each group. The advantage of this approach is that
331 Apache only has to check one file, rather than two. The
332 disadvantage is that you have to maintain a bunch of password
333 files, and remember to reference the right one in the
334 <directive module="mod_authn_file">AuthUserFile</directive> directive.</p>
337 <section id="possibleproblems"><title>Possible problems</title>
338 <p>Because of the way that Basic authentication is specified,
339 your username and password must be verified every time you
340 request a document from the server. This is even if you're
341 reloading the same page, and for every image on the page (if
342 they come from a protected directory). As you can imagine, this
343 slows things down a little. The amount that it slows things
344 down is proportional to the size of the password file, because
345 it has to open up that file, and go down the list of users
346 until it gets to your name. And it has to do this every time a
349 <p>A consequence of this is that there's a practical limit to
350 how many users you can put in one password file. This limit
351 will vary depending on the performance of your particular
352 server machine, but you can expect to see slowdowns once you
353 get above a few hundred entries, and may wish to consider a
354 different authentication method at that time.</p>
357 <section id="dbmdbd"><title>Alternate password storage</title>
359 <p>Because storing passwords in plain text files has the above
360 problems, you may wish to store your passwords somewhere else, such
361 as in a database.</p>
363 <p><module>mod_authn_dbm</module> and <module>mod_authn_dbd</module> are two
364 modules which make this possible. Rather than selecting <code><directive
365 module="mod_auth_basic">AuthBasicProvider</directive> file</code>, instead
366 you can choose <code>dbm</code> or <code>dbd</code> as your storage
369 <p>To select a dbd file rather than a text file, for example:</p>
372 <Directory /www/docs/private><br />
373 AuthName "Private"<br />
375 AuthBasicProvider dbm<br />
376 AuthDBMUserFile /www/passwords/passwd.dbm<br />
377 Require valid-user<br />
381 <p>Other options are available. Consult the
382 <module>mod_authn_dbm</module> documentation for more details.</p>
385 <section id="multprovider"><title>Using multiple providers</title>
387 <p>With the introduction of the new provider based authentication and
388 authorization architecture, you are no longer locked into a single
389 authentication or authorization method. In fact any number of the
390 providers can be mixed and matched to provide you with exactly the
391 scheme that meets your needs. In the following example, both the
392 file and LDAP based authentication providers are being used.</p>
395 <Directory /www/docs/private><br />
396 AuthName "Private"<br />
398 AuthBasicProvider file ldap<br />
399 AuthUserFile /usr/local/apache/passwd/passwords<br />
400 AuthLDAPURL ldap://ldaphost/o=yourorg<br />
401 Require valid-user<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 an 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<br />
431 <p>To take authorization a little further, authorization container
433 <directive module="mod_authz_core" type="section">RequireAll</directive>
435 <directive module="mod_authz_core" type="section">RequireAny</directive>
436 allow logic to be applied so that the order in which authorization
437 is handled can be completely controled through the configuration.
438 See <a href="../mod/mod_authz_core.html#logic">Authorization
439 Containers</a> for an example of they may be applied.</p>
443 <section id="beyond"><title>Beyond just authorization</title>
445 <p>The way that authorization can be apply is now much more flexible
446 than just a single check against a single data store. Ordering, logic
447 and choosing how authorization will be done is now possible.</p>
449 <section id="authandororder"><title>Applying logic and ordering</title>
450 <p>Controling how and in what order authorization will be applied
451 has been a bit of a mystery in the past. In Apache 2.2 a provider-based
452 authentication mechanism was introduced to decouple the actual
453 authentication process from authorization and supporting functionality.
454 One of the side benefits was that authentication providers could be
455 configured and called in a specific order which didn't depend on the
456 load order of the auth module itself. This same provider based mechanism
457 has been brought forward into authorization as well. What this means is
458 that the <directive module="mod_authz_core">Require</directive> directive
459 not only specifies which authorization methods should be used, it also
460 specifies the order in which they are called. Multiple authorization
461 methods are called in the same order in which the
462 <directive module="mod_authz_core">Require</directive> directives
463 appear in the configuration.</p>
465 <p>With the introduction of authorization container directives
467 <directive module="mod_authz_core" type="section">RequireAll</directive>
469 <directive module="mod_authz_core" type="section">RequireAny</directive>,
470 the configuration also has control over when the
471 authorization methods are called and what criteria determines when
472 access is granted. See
473 <a href="../mod/mod_authz_core.html#logic">Authorization Containers</a>
474 for an example of how they may be used to express complex
475 authorization logic.</p>
478 <directive module="mod_authz_core">Require</directive>
479 directives are handled as though contained within a
480 <directive module="mod_authz_core" type="section">RequireAny</directive>
481 container directive. In other words, if
482 any of the specified authorization methods succeed, then authorization
487 <section id="reqaccessctrl"><title>Using authorization providers for access control</title>
488 <p>Authentication by username and password is only part of the
489 story. Frequently you want to let people in based on something
490 other than who they are. Something such as where they are
493 <p>The authorization providers <directive module="mod_authz_host">
494 all</directive>, <directive module="mod_authz_host">
495 env</directive>, <directive module="mod_authz_host">
496 host</directive> and <directive module="mod_authz_host">
497 ip</directive> let you allow or deny access based other host based
498 criteria such as host name or ip address of the machine requesting
501 <p>The usage of these providers is specified through the
502 <directive module="mod_authz_core">Require</directive> directive.
503 This directive registers the authorization providers
504 that will be called during the authorization stage of the request
505 processing. For example:</p>
508 Require ip <var>address</var>
511 <p>where <var>address</var> is an IP address (or a partial IP
515 Require host <var>domain_name</var>
518 <p>where <var>domain_name</var> is a fully qualified domain name
519 (or a partial domain name); you may provide multiple addresses or
520 domain names, if desired.</p>
522 <p>For example, if you have someone spamming your message
523 board, and you want to keep them out, you could do the
529 Require all granted<br/>
530 Require not ip 10.252.46.165
535 <p>Visitors coming from that address will not be able to see
536 the content covered by this directive. If, instead, you have a
537 machine name, rather than an IP address, you can use that.</p>
542 Require all granted<br/>
543 Require not host <var>host.example.com</var>
548 <p>And, if you'd like to block access from an entire domain,
549 you can specify just part of an address or domain name:</p>
554 Require all granted<br/>
557 Require ip 192.168.205<br />
558 Require host phishers.example.com moreidiots.example<br />
566 <p>The above example uses the <directive module="mod_authz_core"
567 type="section">RequireNone</directive> directive
568 to make sure that none of the
569 <directive module="mod_authz_core">Require</directive> directives
571 match their parameters before granting access.</p>
575 <section id="filesystem"><title>Access Control backwards compatibility</title>
576 <p>One of the side effects of adopting a provider based mechanism for
577 authentication is that the need for the previous access control directives
578 <directive module="mod_access_compat">Order</directive>,
579 <directive module="mod_access_compat">Allow</directive>,
580 <directive module="mod_access_compat">Deny</directive> and
581 <directive module="mod_access_compat">Satisfy</directive> are no longer needed.
582 However to provide backwards compatibility for older configurations, these
583 directives have been moved to the <module>mod_access_compat</module> module.</p>
588 <section id="moreinformation"><title>More information</title>
589 <p>You should also read the documentation for
590 <module>mod_auth_basic</module> and <module>mod_authz_host</module> which
591 contain some more information about how this all works.
592 The directive <directive module="mod_authn_core"><AuthnProviderAlias></directive>
593 can also help in simplifying certain authentication configurations.</p>
595 <p>The various ciphers supported by Apache for authentication data are
596 explained in <a href="../misc/password_encryptions.html">Password
599 <p>And you may want to look at the <a href="access.html">Access
600 Control</a> howto, which discusses a number of related topics.</p>