auth.xml revision 91f378b5a10f2d83820902ed10ba7967a3920c18
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder<!DOCTYPE manualpage SYSTEM "/style/manualpage.dtd">
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder<!-- $LastChangedRevision$ -->
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder Licensed to the Apache Software Foundation (ASF) under one or more
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder contributor license agreements. See the NOTICE file distributed with
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder this work for additional information regarding copyright ownership.
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder The ASF licenses this file to You under the Apache License, Version 2.0
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder (the "License"); you may not use this file except in compliance with
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder the License. You may obtain a copy of the License at
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder Unless required by applicable law or agreed to in writing, software
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder distributed under the License is distributed on an "AS IS" BASIS,
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder See the License for the specific language governing permissions and
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder limitations under the License.
fe216849cef7b87c6800aad21178d1e686575d8fChristian Maeder<parentdocument href="./">How-To / Tutorials</parentdocument>
bec7e681b0ba4d085638ec7af0cf7ae5068840caChristian Maeder<title>Authentication, Authorization and Access Control</title>
7b27b67b1c8516d7ccf1610a17fec93662d6a93fChristian Maeder <p>Authentication is any process by which you verify that
b7b2eb9d574f5ed3ac3e9e1d7a5f168ed78a0604Till Mossakowski someone is who they claim they are. Authorization is any
0678d323bee844db79af13113ae252546629a594Christian Maeder process by which someone is allowed to be where they want to
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder go, or to have information that they want to have.</p>
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder<section id="related"><title>Related Modules and Directives</title>
7b27b67b1c8516d7ccf1610a17fec93662d6a93fChristian Maeder<p>There are three types of modules involved in the authentication and
7b27b67b1c8516d7ccf1610a17fec93662d6a93fChristian Maederauthorization process. You will usually need to choose at least one
7b27b67b1c8516d7ccf1610a17fec93662d6a93fChristian Maedermodule from each group.</p>
7b27b67b1c8516d7ccf1610a17fec93662d6a93fChristian Maeder <li>Authentication type (see the
bec7e681b0ba4d085638ec7af0cf7ae5068840caChristian Maeder <directive module="mod_authn_core">AuthType</directive> directive)
bec7e681b0ba4d085638ec7af0cf7ae5068840caChristian Maeder <li>Authentication provider (see the
bec7e681b0ba4d085638ec7af0cf7ae5068840caChristian Maeder <directive module="mod_auth_basic">AuthBasicProvider</directive> and
7b27b67b1c8516d7ccf1610a17fec93662d6a93fChristian Maeder <directive module="mod_auth_digest">AuthDigestProvider</directive> directives)
bec7e681b0ba4d085638ec7af0cf7ae5068840caChristian Maeder <li>Authorization (see the
bec7e681b0ba4d085638ec7af0cf7ae5068840caChristian Maeder <directive module="mod_authz_core">Require</directive> directive)
bec7e681b0ba4d085638ec7af0cf7ae5068840caChristian Maeder <li><module>mod_authz_groupfile</module></li>
a255351561838b3743d03c1629d335cfb8b83804Christian Maeder <p>In addition to these modules, there are also
a255351561838b3743d03c1629d335cfb8b83804Christian Maeder <module>mod_authz_core</module>. These module implement core
f7d2e793728bbb7fd185e027eb9dfd7b9dd11c21Christian Maeder directives that are core to all auth modules.</p>
fe216849cef7b87c6800aad21178d1e686575d8fChristian Maeder <p>The module <module>mod_authnz_ldap</module> is both an
f7d2e793728bbb7fd185e027eb9dfd7b9dd11c21Christian Maeder authentication and authorization provider. The module
02a2037f53b925617df45eb62ca743d777672265Klaus Luettich <module>mod_authz_host</module> provides authorization
02a2037f53b925617df45eb62ca743d777672265Klaus Luettich and access control based on hostname, IP address or characteristics
02a2037f53b925617df45eb62ca743d777672265Klaus Luettich of the request, but is not part of the authentication provider
02a2037f53b925617df45eb62ca743d777672265Klaus Luettich system. For backwards compatibility with the mod_access, there is
02a2037f53b925617df45eb62ca743d777672265Klaus Luettich a new module <module>mod_access_compat</module>.</p>
5908cc06d7a3f4dd46d2d7c7fe0fad43b6cd921fChristian Maeder <p>You probably also want to take a look at the <a
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder href="access.html">Access Control</a> howto, which discusses the
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder various ways to control access to your server.</p>
02a2037f53b925617df45eb62ca743d777672265Klaus Luettich<section id="introduction"><title>Introduction</title>
a255351561838b3743d03c1629d335cfb8b83804Christian Maeder <p>If you have information on your web site that is sensitive
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian Maeder or intended for only a small group of people, the techniques in
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian Maeder this article will help you make sure that the people that see
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian Maeder those pages are the people that you wanted to see them.</p>
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian Maeder <p>This article covers the "standard" way of protecting parts
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian Maeder of your web site that most of you are going to use.</p>
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian Maeder <p>If your data really needs to be secure, consider using
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian Maeder <module>mod_ssl</module> in addition to any authentication.</p>
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian Maeder<section id="theprerequisites"><title>The Prerequisites</title>
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian Maeder <p>The directives discussed in this article will need to go
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian Maeder either in your main server configuration file (typically in a
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian Maeder <directive module="core" type="section">Directory</directive> section), or
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian Maeder in per-directory configuration files (<code>.htaccess</code> files).</p>
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder <p>If you plan to use <code>.htaccess</code> files, you will
f7d2e793728bbb7fd185e027eb9dfd7b9dd11c21Christian Maeder need to have a server configuration that permits putting
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian Maeder authentication directives in these files. This is done with the
a255351561838b3743d03c1629d335cfb8b83804Christian Maeder <directive module="core">AllowOverride</directive> directive, which
f7d2e793728bbb7fd185e027eb9dfd7b9dd11c21Christian Maeder specifies which directives, if any, may be put in per-directory
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder configuration files.</p>
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder <p>Since we're talking here about authentication, you will need
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder an <directive module="core">AllowOverride</directive> directive like the
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder following:</p>
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian Maeder AllowOverride AuthConfig
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian Maeder <p>Or, if you are just going to put the directives directly in
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian Maeder your main server configuration file, you will of course need to
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian Maeder have write permission to that file.</p>
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder <p>And you'll need to know a little bit about the directory
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian Maeder structure of your server, in order to know where some files are
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder kept. This should not be terribly difficult, and I'll try to
fe216849cef7b87c6800aad21178d1e686575d8fChristian Maeder make this clear when we come to that point.</p>
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian Maeder <p>You will also need to make sure that the modules
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder <module>mod_authn_core</module> and <module>mod_authz_core</module>
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian Maeder have either been built into the httpd binary or loaded by the
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian Maeder httpd.conf configuration file. Both of these modules provide core
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian Maeder directives and functionality that are critical to the configuration
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian Maeder and use of authentication and authorization in the web server.</p>
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian Maeder<section id="gettingitworking"><title>Getting it working</title>
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder <p>Here's the basics of password protecting a directory on your
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian Maeder <p>First, you need to create a password file. Exactly how you do
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder this will vary depending on what authentication provider you have
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder chosen. More on that later. To start with, we'll use a text password
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder <p>This file should be
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder placed somewhere not accessible from the web. This is so that
91f4f0335ac32768d819e202263f713aef5d7fe6Christian Maeder folks cannot download the password file. For example, if your
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder documents are served out of <code>/usr/local/apache/htdocs</code> you
36fcac4cf0f6a1f8a0fee696ac7f4b91d769843cChristian Maeder might want to put the password file(s) in
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian Maeder <p>To create the file, use the <program>htpasswd</program> utility that
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian Maeder came with Apache. This will be located in the <code>bin</code> directory
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian Maeder of wherever you installed Apache. If you have installed Apache from
0678d323bee844db79af13113ae252546629a594Christian Maeder a third-party package, it may be in your execution path.</p>
36fcac4cf0f6a1f8a0fee696ac7f4b91d769843cChristian Maeder htpasswd -c /usr/local/apache/passwd/passwords rbowen
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder <p><program>htpasswd</program> will ask you for the password, and
b7b2eb9d574f5ed3ac3e9e1d7a5f168ed78a0604Till Mossakowski then ask you to type it again to confirm it:</p>
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder # htpasswd -c /usr/local/apache/passwd/passwords rbowen<br />
0678d323bee844db79af13113ae252546629a594Christian Maeder New password: mypassword<br />
0678d323bee844db79af13113ae252546629a594Christian Maeder Re-type new password: mypassword<br />
0678d323bee844db79af13113ae252546629a594Christian Maeder Adding password for user rbowen
0678d323bee844db79af13113ae252546629a594Christian Maeder <p>If <program>htpasswd</program> is not in your path, of course
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder you'll have to type the full path to the file to get it to run.
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder With a default installation, it's located at
b7b2eb9d574f5ed3ac3e9e1d7a5f168ed78a0604Till Mossakowski <code>/usr/local/apache2/bin/htpasswd</code></p>
0678d323bee844db79af13113ae252546629a594Christian Maeder <p>Next, you'll need to configure the server to request a
0678d323bee844db79af13113ae252546629a594Christian Maeder password and tell the server which users are allowed access.
0678d323bee844db79af13113ae252546629a594Christian Maeder You can do this either by editing the <code>httpd.conf</code>
0678d323bee844db79af13113ae252546629a594Christian Maeder file or using an <code>.htaccess</code> file. For example, if
0678d323bee844db79af13113ae252546629a594Christian Maeder you wish to protect the directory
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder <code>/usr/local/apache/htdocs/secret</code>, you can use the
0678d323bee844db79af13113ae252546629a594Christian Maeder following directives, either placed in the file
0678d323bee844db79af13113ae252546629a594Christian Maeder <code>/usr/local/apache/htdocs/secret/.htaccess</code>, or
0678d323bee844db79af13113ae252546629a594Christian Maeder placed in <code>httpd.conf</code> inside a <Directory
0678d323bee844db79af13113ae252546629a594Christian Maeder /usr/local/apache/htdocs/secret> section.</p>
0678d323bee844db79af13113ae252546629a594Christian Maeder AuthType Basic<br />
0678d323bee844db79af13113ae252546629a594Christian Maeder AuthName "Restricted Files"<br />
0678d323bee844db79af13113ae252546629a594Christian Maeder # (Following line optional)<br />
fe216849cef7b87c6800aad21178d1e686575d8fChristian Maeder AuthBasicProvider file<br />
fe216849cef7b87c6800aad21178d1e686575d8fChristian Maeder AuthUserFile /usr/local/apache/passwd/passwords<br />
0678d323bee844db79af13113ae252546629a594Christian Maeder Require user rbowen
0678d323bee844db79af13113ae252546629a594Christian Maeder <p>Let's examine each of those directives individually. The <directive
0678d323bee844db79af13113ae252546629a594Christian Maeder module="mod_authn_core">AuthType</directive> directive selects
0678d323bee844db79af13113ae252546629a594Christian Maeder that method that is used to authenticate the user. The most
0678d323bee844db79af13113ae252546629a594Christian Maeder common method is <code>Basic</code>, and this is the method
0678d323bee844db79af13113ae252546629a594Christian Maeder implemented by <module>mod_auth_basic</module>. It is important to be aware,
0678d323bee844db79af13113ae252546629a594Christian Maeder however, that Basic authentication sends the password from the client to
0678d323bee844db79af13113ae252546629a594Christian Maeder the server unencrypted. This method should therefore not be used for
0678d323bee844db79af13113ae252546629a594Christian Maeder highly sensitive data, unless accompanied by <module>mod_ssl</module>.
0678d323bee844db79af13113ae252546629a594Christian Maeder Apache supports one other authentication method:
0678d323bee844db79af13113ae252546629a594Christian Maeder <code>AuthType Digest</code>. This method is implemented by <module
0678d323bee844db79af13113ae252546629a594Christian Maeder >mod_auth_digest</module> and is much more secure. Most recent
0678d323bee844db79af13113ae252546629a594Christian Maeder browsers support Digest authentication.</p>
0678d323bee844db79af13113ae252546629a594Christian Maeder <p>The <directive module="mod_authn_core">AuthName</directive> directive sets
0678d323bee844db79af13113ae252546629a594Christian Maeder the <dfn>Realm</dfn> to be used in the authentication. The realm serves
0678d323bee844db79af13113ae252546629a594Christian Maeder two major functions. First, the client often presents this information to
0678d323bee844db79af13113ae252546629a594Christian Maeder the user as part of the password dialog box. Second, it is used by the
0678d323bee844db79af13113ae252546629a594Christian Maeder client to determine what password to send for a given authenticated
0678d323bee844db79af13113ae252546629a594Christian Maeder <p>So, for example, once a client has authenticated in the
f7d2e793728bbb7fd185e027eb9dfd7b9dd11c21Christian Maeder <code>"Restricted Files"</code> area, it will automatically
0678d323bee844db79af13113ae252546629a594Christian Maeder retry the same password for any area on the same server that is
0678d323bee844db79af13113ae252546629a594Christian Maeder marked with the <code>"Restricted Files"</code> Realm.
0678d323bee844db79af13113ae252546629a594Christian Maeder Therefore, you can prevent a user from being prompted more than
0678d323bee844db79af13113ae252546629a594Christian Maeder once for a password by letting multiple restricted areas share
0678d323bee844db79af13113ae252546629a594Christian Maeder the same realm. Of course, for security reasons, the client
0678d323bee844db79af13113ae252546629a594Christian Maeder will always need to ask again for the password whenever the
0678d323bee844db79af13113ae252546629a594Christian Maeder hostname of the server changes.</p>
0678d323bee844db79af13113ae252546629a594Christian Maeder module="mod_auth_basic">AuthBasicProvider</directive> is,
0678d323bee844db79af13113ae252546629a594Christian Maeder in this case, optional, since <code>file</code> is the default value
0678d323bee844db79af13113ae252546629a594Christian Maeder for this directive. You'll need to use this directive if you are
0678d323bee844db79af13113ae252546629a594Christian Maeder choosing a different source for authentication, such as
0678d323bee844db79af13113ae252546629a594Christian Maeder <module>mod_authn_dbm</module> or <module>mod_authn_dbd</module>.</p>
0678d323bee844db79af13113ae252546629a594Christian Maeder <p>The <directive module="mod_authn_file">AuthUserFile</directive>
0678d323bee844db79af13113ae252546629a594Christian Maeder directive sets the path to the password file that we just
0678d323bee844db79af13113ae252546629a594Christian Maeder created with <program>htpasswd</program>. If you have a large number
0678d323bee844db79af13113ae252546629a594Christian Maeder of users, it can be quite slow to search through a plain text
0678d323bee844db79af13113ae252546629a594Christian Maeder file to authenticate the user on each request. Apache also has
0678d323bee844db79af13113ae252546629a594Christian Maeder the ability to store user information in fast database files.
3ef9708a35cddb7ba66458ad4a065de549ce7db6Till Mossakowski The <module>mod_authn_dbm</module> module provides the <directive
0678d323bee844db79af13113ae252546629a594Christian Maeder module="mod_authn_dbm">AuthDBMUserFile</directive> directive. These
0678d323bee844db79af13113ae252546629a594Christian Maeder files can be created and manipulated with the <program>
0678d323bee844db79af13113ae252546629a594Christian Maeder dbmmanage</program> program. Many
0678d323bee844db79af13113ae252546629a594Christian Maeder other types of authentication options are available from third
0678d323bee844db79af13113ae252546629a594Christian Maeder party modules in the <a
0678d323bee844db79af13113ae252546629a594Christian Maeder href="http://modules.apache.org/">Apache Modules
0678d323bee844db79af13113ae252546629a594Christian Maeder <p>Finally, the <directive module="mod_authz_core">Require</directive>
f7d2e793728bbb7fd185e027eb9dfd7b9dd11c21Christian Maeder directive provides the authorization part of the process by
0678d323bee844db79af13113ae252546629a594Christian Maeder setting the user that is allowed to access this region of the
0678d323bee844db79af13113ae252546629a594Christian Maeder server. In the next section, we discuss various ways to use the
0678d323bee844db79af13113ae252546629a594Christian Maeder <directive module="mod_authz_core">Require</directive> directive.</p>