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
51 <li><module>mod_authn_alias</module></li>
52 <li><module>mod_authn_anon</module></li>
53 <li><module>mod_authn_dbd</module></li>
54 <li><module>mod_authn_dbm</module></li>
55 <li><module>mod_authn_default</module></li>
56 <li><module>mod_authn_file</module></li>
57 <li><module>mod_authnz_ldap</module></li>
60 <li>Authorization (see the
61 <directive module="core">Require</directive> directive)
63 <li><module>mod_authnz_ldap</module></li>
64 <li><module>mod_authz_dbm</module></li>
65 <li><module>mod_authz_default</module></li>
66 <li><module>mod_authz_groupfile</module></li>
67 <li><module>mod_authz_owner</module></li>
68 <li><module>mod_authz_user</module></li>
73 <p>The module <module>mod_authnz_ldap</module> is both an
74 authentication and authorization provider. The module
75 <module>mod_authn_alias</module> is not an authentication provider
76 in itself, but allows other authentication providers to be
77 configured in a flexible manner.</p>
79 <p>The module <module>mod_authz_host</module> provides authorization
80 and access control based on hostname, IP address or characteristics
81 of the request, but is not part of the authentication provider
84 <p>You probably also want to take a look at the <a
85 href="access.html">Access Control</a> howto, which discusses the
86 various ways to control access to your server.</p>
90 <section id="introduction"><title>Introduction</title>
91 <p>If you have information on your web site that is sensitive
92 or intended for only a small group of people, the techniques in
93 this article will help you make sure that the people that see
94 those pages are the people that you wanted to see them.</p>
96 <p>This article covers the "standard" way of protecting parts
97 of your web site that most of you are going to use.</p>
99 <note><title>Note:</title>
100 <p>If your data really needs to be secure, consider using
101 <module>mod_ssl</module> in addition to any authentication.</p>
105 <section id="theprerequisites"><title>The Prerequisites</title>
106 <p>The directives discussed in this article will need to go
107 either in your main server configuration file (typically in a
108 <directive module="core" type="section">Directory</directive> section), or
109 in per-directory configuration files (<code>.htaccess</code> files).</p>
111 <p>If you plan to use <code>.htaccess</code> files, you will
112 need to have a server configuration that permits putting
113 authentication directives in these files. This is done with the
114 <directive module="core">AllowOverride</directive> directive, which
115 specifies which directives, if any, may be put in per-directory
116 configuration files.</p>
118 <p>Since we're talking here about authentication, you will need
119 an <directive module="core">AllowOverride</directive> directive like the
123 AllowOverride AuthConfig
126 <p>Or, if you are just going to put the directives directly in
127 your main server configuration file, you will of course need to
128 have write permission to that file.</p>
130 <p>And you'll need to know a little bit about the directory
131 structure of your server, in order to know where some files are
132 kept. This should not be terribly difficult, and I'll try to
133 make this clear when we come to that point.</p>
136 <section id="gettingitworking"><title>Getting it working</title>
137 <p>Here's the basics of password protecting a directory on your
140 <p>First, you need to create a password file. Exactly how you do
141 this will vary depending on what authentication provider you have
142 chosen. More on that later. To start with, we'll use a text password
145 <p>This file should be
146 placed somewhere not accessible from the web. This is so that
147 folks cannot download the password file. For example, if your
148 documents are served out of <code>/usr/local/apache/htdocs</code> you
149 might want to put the password file(s) in
150 <code>/usr/local/apache/passwd</code>.</p>
152 <p>To create the file, use the <program>htpasswd</program> utility that
153 came with Apache. This will be located in the <code>bin</code> directory
154 of wherever you installed Apache. If you have installed Apache from
155 a third-party package, it may be in your execution path.</p>
157 <p>To create the file, type:</p>
160 htpasswd -c /usr/local/apache/passwd/passwords rbowen
163 <p><program>htpasswd</program> will ask you for the password, and
164 then ask you to type it again to confirm it:</p>
167 # htpasswd -c /usr/local/apache/passwd/passwords rbowen<br />
168 New password: mypassword<br />
169 Re-type new password: mypassword<br />
170 Adding password for user rbowen
173 <p>If <program>htpasswd</program> is not in your path, of course
174 you'll have to type the full path to the file to get it to run.
175 With a default installation, it's located at
176 <code>/usr/local/apache2/bin/htpasswd</code></p>
178 <p>Next, you'll need to configure the server to request a
179 password and tell the server which users are allowed access.
180 You can do this either by editing the <code>httpd.conf</code>
181 file or using an <code>.htaccess</code> file. For example, if
182 you wish to protect the directory
183 <code>/usr/local/apache/htdocs/secret</code>, you can use the
184 following directives, either placed in the file
185 <code>/usr/local/apache/htdocs/secret/.htaccess</code>, or
186 placed in <code>httpd.conf</code> inside a <Directory
187 /usr/local/apache/apache/htdocs/secret> section.</p>
191 AuthName "Restricted Files"<br />
192 # (Following line optional)<br />
193 AuthBasicProvider file<br />
194 AuthUserFile /usr/local/apache/passwd/passwords<br />
198 <p>Let's examine each of those directives individually. The <directive
199 module="core">AuthType</directive> directive selects
200 that method that is used to authenticate the user. The most
201 common method is <code>Basic</code>, and this is the method
202 implemented by <module>mod_auth_basic</module>. It is important to be aware,
203 however, that Basic authentication sends the password from the client to
204 the server unencrypted. This method should therefore not be used for
205 highly sensitive data, unless accompanied by <module>mod_ssl</module>.
206 Apache supports one other authentication method:
207 <code>AuthType Digest</code>. This method is implemented by <module
208 >mod_auth_digest</module> and is much more secure. Most recent
209 browsers support Digest authentication.</p>
211 <p>The <directive module="core">AuthName</directive> directive sets
212 the <dfn>Realm</dfn> to be used in the authentication. The realm serves
213 two major functions. First, the client often presents this information to
214 the user as part of the password dialog box. Second, it is used by the
215 client to determine what password to send for a given authenticated
218 <p>So, for example, once a client has authenticated in the
219 <code>"Restricted Files"</code> area, it will automatically
220 retry the same password for any area on the same server that is
221 marked with the <code>"Restricted Files"</code> Realm.
222 Therefore, you can prevent a user from being prompted more than
223 once for a password by letting multiple restricted areas share
224 the same realm. Of course, for security reasons, the client
225 will always need to ask again for the password whenever the
226 hostname of the server changes.</p>
229 module="mod_auth_basic">AuthBasicProvider</directive> is,
230 in this case, optional, since <code>file</code> is the default value
231 for this directive. You'll need to use this directive if you are
232 choosing a different source for authentication, such as
233 <module>mod_authn_dbm</module> or <module>mod_authn_dbd</module>.</p>
235 <p>The <directive module="mod_authn_file">AuthUserFile</directive>
236 directive sets the path to the password file that we just
237 created with <program>htpasswd</program>. If you have a large number
238 of users, it can be quite slow to search through a plain text
239 file to authenticate the user on each request. Apache also has
240 the ability to store user information in fast database files.
241 The <module>mod_authn_dbm</module> module provides the <directive
242 module="mod_authn_dbm">AuthDBMUserFile</directive> directive. These
243 files can be created and manipulated with the <program>
244 dbmmanage</program> program. Many
245 other types of authentication options are available from third
246 party modules in the <a
247 href="http://modules.apache.org/">Apache Modules
250 <p>Finally, the <directive module="core">Require</directive>
251 directive provides the authorization part of the process by
252 setting the user that is allowed to access this region of the
253 server. In the next section, we discuss various ways to use the
254 <directive module="core">Require</directive> directive.</p>
257 <section id="lettingmorethanonepersonin"><title>Letting more than one
259 <p>The directives above only let one person (specifically
260 someone with a username of <code>rbowen</code>) into the
261 directory. In most cases, you'll want to let more than one
262 person in. This is where the <directive module="mod_authz_groupfile"
263 >AuthGroupFile</directive> comes in.</p>
265 <p>If you want to let more than one person in, you'll need to
266 create a group file that associates group names with a list of
267 users in that group. The format of this file is pretty simple,
268 and you can create it with your favorite editor. The contents
269 of the file will look like this:</p>
272 GroupName: rbowen dpitts sungo rshersey
275 <p>That's just a list of the members of the group in a long
276 line separated by spaces.</p>
278 <p>To add a user to your already existing password file,
282 htpasswd /usr/local/apache/passwd/passwords dpitts
285 <p>You'll get the same response as before, but it will be
286 appended to the existing file, rather than creating a new file.
287 (It's the <code>-c</code> that makes it create a new password
290 <p>Now, you need to modify your <code>.htaccess</code> file to
291 look like the following:</p>
295 AuthName "By Invitation Only"<br />
297 AuthBasicProvider file
298 AuthUserFile /usr/local/apache/passwd/passwords<br />
299 AuthGroupFile /usr/local/apache/passwd/groups<br />
300 Require group GroupName
303 <p>Now, anyone that is listed in the group <code>GroupName</code>,
304 and has an entry in the <code>password</code> file, will be let in, if
305 they type the correct password.</p>
307 <p>There's another way to let multiple users in that is less
308 specific. Rather than creating a group file, you can just use
309 the following directive:</p>
315 <p>Using that rather than the <code>Require user rbowen</code>
316 line will allow anyone in that is listed in the password file,
317 and who correctly enters their password. You can even emulate
318 the group behavior here, by just keeping a separate password
319 file for each group. The advantage of this approach is that
320 Apache only has to check one file, rather than two. The
321 disadvantage is that you have to maintain a bunch of password
322 files, and remember to reference the right one in the
323 <directive module="mod_authn_file">AuthUserFile</directive> directive.</p>
326 <section id="possibleproblems"><title>Possible problems</title>
327 <p>Because of the way that Basic authentication is specified,
328 your username and password must be verified every time you
329 request a document from the server. This is even if you're
330 reloading the same page, and for every image on the page (if
331 they come from a protected directory). As you can imagine, this
332 slows things down a little. The amount that it slows things
333 down is proportional to the size of the password file, because
334 it has to open up that file, and go down the list of users
335 until it gets to your name. And it has to do this every time a
338 <p>A consequence of this is that there's a practical limit to
339 how many users you can put in one password file. This limit
340 will vary depending on the performance of your particular
341 server machine, but you can expect to see slowdowns once you
342 get above a few hundred entries, and may wish to consider a
343 different authentication method at that time.</p>
346 <section id="dbmdbd"><title>Alternate password storage</title>
348 <p>Because storing passwords in plain text files has the above
349 problems, you may wish to store your passwords somewhere else, such
350 as in a database.</p>
352 <p><module>mod_authn_dbm</module> and <module>mod_authn_dbd</module>
353 are two modules which make this possible. Rather than selecting
354 <directive module="mod_auth_basic">AuthBasicSource</directive> file,
355 instead you can choose <code>dbm</code> or <code>dbd</code> as your
358 <p>To select a dbd file rather than a text file, for example:</p>
361 <Directory /www/docs/private><br />
362 AuthName "Private"<br />
364 AuthBasicProvider dbm<br />
365 AuthDBMUserFile /www/passwords/passwd.dbm<br />
369 <p>Other options are available. Consult the
370 <module>mod_authn_dbm</module> documentation for more details.</p>
373 <section id="moreinformation"><title>More information</title>
374 <p>You should also read the documentation for
375 <module>mod_auth_basic</module> and <module>mod_authz_host</module> which
376 contain some more information about how this all works.
377 <module>mod_authn_alias</module> can also help in simplifying certain
378 authentication configurations.</p>
380 <p>And you may want to look at the <a href="access.html">Access
381 Control</a> howto, which discusses a number of related topics.</p>