Apache Server Frequently Asked Questions

$Revision: 1.4 $ ($Date: 2000/09/12 15:16:45 $)

The latest version of this FAQ is always available from the main Apache web site, at <http://www.apache.org/docs/misc/FAQ.html>.

If you are reading a text-only version of this FAQ, you may find numbers enclosed in brackets (such as "[12]"). These refer to the list of reference URLs to be found at the end of the document. These references do not appear, and are not needed, for the hypertext version.

The Questions

7. Authentication and Access Restrictions
   1. Why isn't restricting access by host or domain name working correctly?
   2. How do I set up Apache to require a username and password to access certain documents?
   3. How do I set up Apache to allow access to certain documents only if a site is either a local site or the user supplies a password and username?
   4. Why does my authentication give me a server error?
   5. Do I have to keep the (mSQL) authentication information on the same machine?
   6. Why is my mSQL authentication terribly slow?
   7. Can I use my /etc/passwd file for Web page authentication?
   8. Why does Apache ask for my password twice before serving a file?

The Answers

G. Authentication and Access Restrictions

1. Why isn't restricting access by host or domain name working correctly?

   Two of the most common causes of this are:

   1. An error, inconsistency, or unexpected mapping in the DNS registration
      This happens frequently: your configuration restricts access to Host.FooBar.Com, but you can't get in from that host. The usual reason for this is that Host.FooBar.Com is actually an alias for another name, and when Apache performs the address-to-name lookup it's getting the real name, not Host.FooBar.Com. You can verify this by checking the reverse lookup yourself. The easiest way to work around it is to specify the correct host name in your configuration.
   2. Inadequate checking and verification in your configuration of Apache
      If you intend to perform access checking and restriction based upon the client's host or domain name, you really need to configure Apache to double-check the origin information it's supplied. You do this by adding the -DMAXIMUM_DNS clause to the EXTRA_CFLAGS definition in your Configuration file. For example:

      EXTRA_CFLAGS=-DMAXIMUM_DNS

      This will cause Apache to be very paranoid about making sure a particular host address is really assigned to the name it claims to be. Note that this can incur a significant performance penalty, however, because of all the name resolution requests being sent to a nameserver.

   ---

2. How do I set up Apache to require a username and password to access certain documents?

   There are several ways to do this; some of the more popular ones are to use the mod_auth, mod_auth_db, or mod_auth_dbm modules.

   For an explanation on how to implement these restrictions, see Apache Week's articles on Using User Authentication or DBM User Authentication.

   ---

3. How do I set up Apache to allow access to certain documents only if a site is either a local site or the user supplies a password and username?

   Use the Satisfy directive, in particular the Satisfy Any directive, to require that only one of the access restrictions be met. For example, adding the following configuration to a .htaccess or server configuration file would restrict access to people who either are accessing the site from a host under domain.com or who can supply a valid username and password:

   Deny from all
Allow from .domain.com
AuthType Basic
AuthUserFile /usr/local/apache/conf/htpasswd.users
AuthName "special directory"
Require valid-user
Satisfy any

   See the user authentication question and the mod_access module for details on how the above directives work.

   ---

4. Why does my authentication give me a server error?

   Under normal circumstances, the Apache access control modules will pass unrecognized user IDs on to the next access control module in line. Only if the user ID is recognized and the password is validated (or not) will it give the usual success or "authentication failed" messages.

   However, if the last access module in line 'declines' the validation request (because it has never heard of the user ID or because it is not configured), the http_request handler will give one of the following, confusing, errors:

   • check access
   • check user. No user file?
   • check access. No groups file?

   This does not mean that you have to add an 'AuthUserFile /dev/null' line as some magazines suggest!

   The solution is to ensure that at least the last module is authoritative and CONFIGURED. By default, mod_auth is authoritative and will give an OK/Denied, but only if it is configured with the proper AuthUserFile. Likewise, if a valid group is required. (Remember that the modules are processed in the reverse order from that in which they appear in your compile-time Configuration file.)

   A typical situation for this error is when you are using the mod_auth_dbm, mod_auth_msql, mod_auth_mysql, mod_auth_anon or mod_auth_cookie modules on their own. These are by default not authoritative, and this will pass the buck on to the (non-existent) next authentication module when the user ID is not in their respective database. Just add the appropriate 'XXXAuthoritative yes' line to the configuration.

   In general it is a good idea (though not terribly efficient) to have the file-based mod_auth a module of last resort. This allows you to access the web server with a few special passwords even if the databases are down or corrupted. This does cost a file open/seek/close for each request in a protected area.

   ---

5. Do I have to keep the (mSQL) authentication information on the same machine?

   Some organizations feel very strongly about keeping the authentication information on a different machine than the webserver. With the mod_auth_msql, mod_auth_mysql, and other SQL modules connecting to (R)DBMses this is quite possible. Just configure an explicit host to contact.

   Be aware that with mSQL and Oracle, opening and closing these database connections is very expensive and time consuming. You might want to look at the code in the auth_* modules and play with the compile time flags to alleviate this somewhat, if your RDBMS licences allow for it.

   ---

6. Why is my mSQL authentication terribly slow?

   You have probably configured the Host by specifying a FQHN, and thus the libmsql will use a full blown TCP/IP socket to talk to the database, rather than a fast internal device. The libmsql, the mSQL FAQ, and the mod_auth_msql documentation warn you about this. If you have to use different hosts, check out the mod_auth_msql code for some compile time flags which might - or might not - suit you.

   ---

7. Can I use my /etc/passwd file for Web page authentication?

   Yes, you can - but it's a very bad idea. Here are some of the reasons:

   • The Web technology provides no governors on how often or how rapidly password (authentication failure) retries can be made. That means that someone can hammer away at your system's root password using the Web, using a dictionary or similar mass attack, just as fast as the wire and your server can handle the requests. Most operating systems these days include attack detection (such as n failed passwords for the same account within m seconds) and evasion (breaking the connection, disabling the account under attack, disabling all logins from that source, et cetera), but the Web does not.
   • An account under attack isn't notified (unless the server is heavily modified); there's no "You have 19483 login failures" message when the legitimate owner logs in.
   • Without an exhaustive and error-prone examination of the server logs, you can't tell whether an account has been compromised. Detecting that an attack has occurred, or is in progress, is fairly obvious, though - if you look at the logs.
   • Web authentication passwords (at least for Basic authentication) generally fly across the wire, and through intermediate proxy systems, in what amounts to plain text. "O'er the net we go/Caching all the way;/O what fun it is to surf/Giving my password away!"
   • Since HTTP is stateless, information about the authentication is transmitted each and every time a request is made to the server. Essentially, the client caches it after the first successful access, and transmits it without asking for all subsequent requests to the same server.
   • It's relatively trivial for someone on your system to put up a page that will steal the cached password from a client's cache without them knowing. Can you say "password grabber"?

   If you still want to do this in light of the above disadvantages, the method is left as an exercise for the reader. It'll void your Apache warranty, though, and you'll lose all accumulated UNIX guru points.

   ---

8. Why does Apache ask for my password twice before serving a file?

   If the hostname under which you are accessing the server is different than the hostname specified in the ServerName directive, then depending on the setting of the UseCanonicalName directive, Apache will redirect you to a new hostname when constructing self-referential URLs. This happens, for example, in the case where you request a directory without including the trailing slash.

   When this happens, Apache will ask for authentication once under the original hostname, perform the redirect, and then ask again under the new hostname. For security reasons, the browser must prompt again for the password when the host name changes.

   To eliminate this problem you should

   1. Always use the trailing slash when requesting directories;
   2. Change the ServerName to match the name you are using in the URL; and/or
   3. Set UseCanonicalName off.

   ---