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 and Authorization</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>
34 <p>For general access control, see the <a href="access.html">Access
35 Control How-To</a>.</p>
38 <section id="related"><title>Related Modules and Directives</title>
40 <p>There are three types of modules involved in the authentication and
41 authorization process. You will usually need to choose at least one
42 module from each group.</p>
45 <li>Authentication type (see the
46 <directive module="mod_authn_core">AuthType</directive> directive)
48 <li><module>mod_auth_basic</module></li>
49 <li><module>mod_auth_digest</module></li>
52 <li>Authentication provider (see the
53 <directive module="mod_auth_basic">AuthBasicProvider</directive> and
54 <directive module="mod_auth_digest">AuthDigestProvider</directive> directives)
57 <li><module>mod_authn_anon</module></li>
58 <li><module>mod_authn_dbd</module></li>
59 <li><module>mod_authn_dbm</module></li>
60 <li><module>mod_authn_file</module></li>
61 <li><module>mod_authnz_ldap</module></li>
62 <li><module>mod_authn_socache</module></li>
65 <li>Authorization (see the
66 <directive module="mod_authz_core">Require</directive> directive)
68 <li><module>mod_authnz_ldap</module></li>
69 <li><module>mod_authz_dbd</module></li>
70 <li><module>mod_authz_dbm</module></li>
71 <li><module>mod_authz_groupfile</module></li>
72 <li><module>mod_authz_host</module></li>
73 <li><module>mod_authz_owner</module></li>
74 <li><module>mod_authz_user</module></li>
79 <p>In addition to these modules, there are also
80 <module>mod_authn_core</module> and
81 <module>mod_authz_core</module>. These module implement core
82 directives that are core to all auth modules.</p>
84 <p>The module <module>mod_authnz_ldap</module> is both an
85 authentication and authorization provider. The module
86 <module>mod_authz_host</module> provides authorization
87 and access control based on hostname, IP address or characteristics
88 of the request, but is not part of the authentication provider
89 system. For backwards compatibility with the mod_access, there is
90 a new module <module>mod_access_compat</module>.</p>
92 <p>You probably also want to take a look at the <a
93 href="access.html">Access Control</a> howto, which discusses the
94 various ways to control access to your server.</p>
98 <section id="introduction"><title>Introduction</title>
99 <p>If you have information on your web site that is sensitive
100 or intended for only a small group of people, the techniques in
101 this article will help you make sure that the people that see
102 those pages are the people that you wanted to see them.</p>
104 <p>This article covers the "standard" way of protecting parts
105 of your web site that most of you are going to use.</p>
107 <note><title>Note:</title>
108 <p>If your data really needs to be secure, consider using
109 <module>mod_ssl</module> in addition to any authentication.</p>
113 <section id="theprerequisites"><title>The Prerequisites</title>
114 <p>The directives discussed in this article will need to go
115 either in your main server configuration file (typically in a
116 <directive module="core" type="section">Directory</directive> section), or
117 in per-directory configuration files (<code>.htaccess</code> files).</p>
119 <p>If you plan to use <code>.htaccess</code> files, you will
120 need to have a server configuration that permits putting
121 authentication directives in these files. This is done with the
122 <directive module="core">AllowOverride</directive> directive, which
123 specifies which directives, if any, may be put in per-directory
124 configuration files.</p>
126 <p>Since we're talking here about authentication, you will need
127 an <directive module="core">AllowOverride</directive> directive like the
130 <highlight language="config">AllowOverride AuthConfig</highlight>
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/htdocs/secret> section.</p>
202 <highlight language="config">
204 AuthName "Restricted Files"
205 # (Following line optional)
206 AuthBasicProvider file
207 AuthUserFile /usr/local/apache/passwd/passwords
211 <p>Let's examine each of those directives individually. The <directive
212 module="mod_authn_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="mod_authn_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="mod_authz_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="mod_authz_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 or
304 <directive module="core" type="section">Directory</directive> block
305 to look like the following:</p>
307 <highlight language="config">
309 AuthName "By Invitation Only"
311 AuthBasicProvider file
312 AuthUserFile /usr/local/apache/passwd/passwords
313 AuthGroupFile /usr/local/apache/passwd/groups
314 Require group GroupName
317 <p>Now, anyone that is listed in the group <code>GroupName</code>,
318 and has an entry in the <code>password</code> file, will be let in, if
319 they type the correct password.</p>
321 <p>There's another way to let multiple users in that is less
322 specific. Rather than creating a group file, you can just use
323 the following directive:</p>
325 <highlight language="config">Require valid-user</highlight>
327 <p>Using that rather than the <code>Require user rbowen</code>
328 line will allow anyone in that is listed in the password file,
329 and who correctly enters their password.</p>
332 <section id="possibleproblems"><title>Possible problems</title>
333 <p>Because of the way that Basic authentication is specified,
334 your username and password must be verified every time you
335 request a document from the server. This is even if you're
336 reloading the same page, and for every image on the page (if
337 they come from a protected directory). As you can imagine, this
338 slows things down a little. The amount that it slows things
339 down is proportional to the size of the password file, because
340 it has to open up that file, and go down the list of users
341 until it gets to your name. And it has to do this every time a
344 <p>A consequence of this is that there's a practical limit to
345 how many users you can put in one password file. This limit
346 will vary depending on the performance of your particular
347 server machine, but you can expect to see slowdowns once you
348 get above a few hundred entries, and may wish to consider a
349 different authentication method at that time.</p>
352 <section id="dbmdbd"><title>Alternate password storage</title>
354 <p>Because storing passwords in plain text files has the above
355 problems, you may wish to store your passwords somewhere else, such
356 as in a database.</p>
358 <p><module>mod_authn_dbm</module> and <module>mod_authn_dbd</module> are two
359 modules which make this possible. Rather than selecting <code><directive
360 module="mod_auth_basic">AuthBasicProvider</directive> file</code>, instead
361 you can choose <code>dbm</code> or <code>dbd</code> as your storage
364 <p>To select a dbd file rather than a text file, for example:</p>
366 <highlight language="config">
367 <Directory /www/docs/private>
371 AuthBasicProvider dbm
372 AuthDBMUserFile /www/passwords/passwd.dbm
378 <p>Other options are available. Consult the
379 <module>mod_authn_dbm</module> documentation for more details.</p>
382 <section id="multprovider"><title>Using multiple providers</title>
384 <p>With the introduction of the new provider based authentication and
385 authorization architecture, you are no longer locked into a single
386 authentication or authorization method. In fact any number of the
387 providers can be mixed and matched to provide you with exactly the
388 scheme that meets your needs. In the following example, both the
389 file and LDAP based authentication providers are being used.</p>
391 <highlight language="config">
392 <Directory /www/docs/private>
396 AuthBasicProvider file ldap
397 AuthUserFile /usr/local/apache/passwd/passwords
398 AuthLDAPURL ldap://ldaphost/o=yourorg
404 <p>In this example the file provider will attempt to authenticate
405 the user first. If it is unable to authenticate the user, the LDAP
406 provider will be called. This allows the scope of authentication
407 to be broadened if your organization implements more than
408 one type of authentication store. Other authentication and authorization
409 scenarios may include mixing one type of authentication with a
410 different type of authorization. For example, authenticating against
411 a password file yet authorizing against an LDAP directory.</p>
413 <p>Just as multiple authentication providers can be implemented, multiple
414 authorization methods can also be used. In this example both file group
415 authorization as well as LDAP group authorization is being used.</p>
417 <highlight language="config">
418 <Directory /www/docs/private>
422 AuthBasicProvider file
423 AuthUserFile /usr/local/apache/passwd/passwords
424 AuthLDAPURL ldap://ldaphost/o=yourorg
425 AuthGroupFile /usr/local/apache/passwd/groups
426 Require group GroupName
427 Require ldap-group cn=mygroup,o=yourorg
432 <p>To take authorization a little further, authorization container
434 <directive module="mod_authz_core" type="section">RequireAll</directive>
436 <directive module="mod_authz_core" type="section">RequireAny</directive>
437 allow logic to be applied so that the order in which authorization
438 is handled can be completely controled through the configuration.
439 See <a href="../mod/mod_authz_core.html#logic">Authorization
440 Containers</a> for an example of they may be applied.</p>
444 <section id="beyond"><title>Beyond just authorization</title>
446 <p>The way that authorization can be apply is now much more flexible
447 than just a single check against a single data store. Ordering, logic
448 and choosing how authorization will be done is now possible.</p>
450 <section id="authandororder"><title>Applying logic and ordering</title>
451 <p>Controling how and in what order authorization will be applied
452 has been a bit of a mystery in the past. In Apache 2.2 a provider-based
453 authentication mechanism was introduced to decouple the actual
454 authentication process from authorization and supporting functionality.
455 One of the side benefits was that authentication providers could be
456 configured and called in a specific order which didn't depend on the
457 load order of the auth module itself. This same provider based mechanism
458 has been brought forward into authorization as well. What this means is
459 that the <directive module="mod_authz_core">Require</directive> directive
460 not only specifies which authorization methods should be used, it also
461 specifies the order in which they are called. Multiple authorization
462 methods are called in the same order in which the
463 <directive module="mod_authz_core">Require</directive> directives
464 appear in the configuration.</p>
466 <p>With the introduction of authorization container directives
468 <directive module="mod_authz_core" type="section">RequireAll</directive>
470 <directive module="mod_authz_core" type="section">RequireAny</directive>,
471 the configuration also has control over when the
472 authorization methods are called and what criteria determines when
473 access is granted. See
474 <a href="../mod/mod_authz_core.html#logic">Authorization Containers</a>
475 for an example of how they may be used to express complex
476 authorization logic.</p>
479 <directive module="mod_authz_core">Require</directive>
480 directives are handled as though contained within a
481 <directive module="mod_authz_core" type="section">RequireAny</directive>
482 container directive. In other words, if
483 any of the specified authorization methods succeed, then authorization
488 <section id="reqaccessctrl"><title>Using authorization providers for access control</title>
489 <p>Authentication by username and password is only part of the
490 story. Frequently you want to let people in based on something
491 other than who they are. Something such as where they are
494 <p>The authorization providers <directive module="mod_authz_host">
495 all</directive>, <directive module="mod_authz_host">
496 env</directive>, <directive module="mod_authz_host">
497 host</directive> and <directive module="mod_authz_host">
498 ip</directive> let you allow or deny access based other host based
499 criteria such as host name or ip address of the machine requesting
502 <p>The usage of these providers is specified through the
503 <directive module="mod_authz_core">Require</directive> directive.
504 This directive registers the authorization providers
505 that will be called during the authorization stage of the request
506 processing. For example:</p>
508 <highlight language="config">Require ip <var>address</var></highlight>
510 <p>where <var>address</var> is an IP address (or a partial IP
513 <highlight language="config">Require host <var>domain_name</var></highlight>
515 <p>where <var>domain_name</var> is a fully qualified domain name
516 (or a partial domain name); you may provide multiple addresses or
517 domain names, if desired.</p>
519 <p>For example, if you have someone spamming your message
520 board, and you want to keep them out, you could do the
523 <highlight language="config">
526 Require not ip 10.252.46.165
530 <p>Visitors coming from that address will not be able to see
531 the content covered by this directive. If, instead, you have a
532 machine name, rather than an IP address, you can use that.</p>
534 <highlight language="config">
537 Require not host host.example.com
541 <p>And, if you'd like to block access from an entire domain,
542 you can specify just part of an address or domain name:</p>
544 <highlight language="config">
547 Require not ip 192.168.205
548 Require not host phishers.example.com moreidiots.example
553 <p>The above example uses the <directive module="mod_authz_core"
554 type="section">RequireNone</directive> directive
555 to make sure that none of the
556 <directive module="mod_authz_core">Require</directive> directives
558 match their parameters before granting access.</p>
562 <section id="filesystem"><title>Access Control backwards compatibility</title>
563 <p>One of the side effects of adopting a provider based mechanism for
564 authentication is that the need for the previous access control directives
565 <directive module="mod_access_compat">Order</directive>,
566 <directive module="mod_access_compat">Allow</directive>,
567 <directive module="mod_access_compat">Deny</directive> and
568 <directive module="mod_access_compat">Satisfy</directive> are no longer needed.
569 However to provide backwards compatibility for older configurations, these
570 directives have been moved to the <module>mod_access_compat</module> module.</p>
575 <section id="socache"><title>Authentication Cacheing</title>
576 <p>There may be times when authentication puts an unacceptable load
577 on a provider or on your network. This is most likely to affect users
578 of <module>mod_authn_dbd</module> (or third-party/custom providers).
579 To deal with this, HTTPD 2.3/2.4 introduces a new cacheing provider
580 <module>mod_authn_socache</module> to cache credentials and reduce
581 the load on the origin provider(s).</p>
582 <p>This may offer a substantial performance boost to some users.</p>
585 <section id="moreinformation"><title>More information</title>
586 <p>You should also read the documentation for
587 <module>mod_auth_basic</module> and <module>mod_authz_host</module> which
588 contain some more information about how this all works.
589 The directive <directive module="mod_authn_core"><AuthnProviderAlias></directive>
590 can also help in simplifying certain authentication configurations.</p>
592 <p>The various ciphers supported by Apache for authentication data are
593 explained in <a href="../misc/password_encryptions.html">Password
596 <p>And you may want to look at the <a href="access.html">Access
597 Control</a> howto, which discusses a number of related topics.</p>