Passwords for Websites on Apache Server

(note: this page is obsolete and has been slated to be rewritten)

Introduction

Frequently you will want to limit access to a website to certain users with passwords. This will show you how.

At Brand X Internet we use a web server software called Apache. Apache is based on an older software called NCSA httpd. The Apache web server software allows you to restrict access based on several criteria:

Username/password-level access authorization.
Rejection or acceptance of connections based on Internet address of client.
A combination of the above two methods.

Tutorial Contents

Introduction
Getting Started
General Information
How Secure is it?
Basic By-Password Authentication: Step By Step
Multiple Usernames/Passwords
More Examples
For More Information

Getting Started

This tutorial assumes that you have access to an Apache web server. If you need a web site, send us an email at support@brandx.net or sales@brandx.net and we will be happy to help you.

Please note that these instructions do not work for Windows based web servers.

General Information

There are two levels at which authentication information can be passed to the server: the global access configuration file and the per-directory configuration files. This tutorial primarily covers per-directory configuration. See the NCSA HTTPd documentation for information on global configuration.

Per-directory configuration means that users with write access to part of the filesystem that is being served (the Document Tree) can control access to their files as they wish. They need not have root access on the system or write access to the server's primary configuration files. Also, the per-directory configuration files are read and parsed by the server on each access, allowing run-time re-configuration. The global configuration files are only parsed on start-up or restart, which usually requires root authority. There is a speed penalty associated with using the per-directory configuration files, but that's the trade-off you have to take.

Access control for a given directory is controlled by a specific file in the directory with a filename as specified in the files srm.conf AccessFileName directive. The default filename is .htaccess. This is the name of the file you will need to create in order to set password access. More on this below.

How Secure Is It?

In Basic HTTP Authentication, the password is passed over the network not encrypted but not as plain text -- it is "uuencoded." Anyone watching packet traffic on the network will not see the password in the clear, but the password will be easily decoded by anyone who happens to catch the right network packet.

So basically this method of authentication is roughly as safe as telnet-style username and password security -- if you trust your machine to be on the Internet, open to attempts to telnet in by anyone who wants to try, then you have no reason not to trust this method also.

In MD5 Message Digest Authentication, the password is not passed over the network at all. Instead, a series of numbers is generated based on the password and other information about the request, and these numbers are then hashed using MD5. The resulting "digest" is then sent over the network, and it is combined with other items on the server to test against the saved digest on the server. This method is more secure over the network, but it has a penalty. The comparison digest on the server must be stored in a fashion that it is retrievable. Basic Authentication stores the password using the one way crypt() function. When the password comes across, the server uudecodes it and then crypts it to check against the stored value. There is no way to get the password from the crypted value. In MD5, you need the information that is stored, so you can't use a one way hashing function to store it. This means that MD5 requires more rigorous security on the server machine. It is possible, but non-trivial, to implement this type of security under the Unix^TM security model.

Basic ByPassword Authentication: Step By Step

This should help you set up protection on a directory via the Basic HTTP Authentication method. This method also uses the standard plaintext password file. If you have a large user base, NCSA HTTPd supports a DBM based password file for faster access.

So let's suppose you want to restrict files in a directory called turkey to username pumpkin and password pie. Here's what to do:

Create a file called .htaccess in directory turkey that looks like this:

AuthUserFile /otherdir/.htpasswd
AuthGroupFile /dev/null
AuthName ByPassword
AuthType Basic

<Limit GET>
require user pumpkin
</Limit>

Note that the password file will be in another directory (/otherdir).

AuthUserFile must be the full Unix pathname of the password file.

Also note that in this case there is no group file, so we specify /dev/null (the standard Unix way to say "this file doesn't exist").

AuthName can be anything you want. The AuthName field gives the Realm name for which the protection is provided. This name is usually given when a browser prompts for a password, and is also usually used by a browser in correlation with the URL to save the password information you enter so that it can authenticate automatically on the next challenge. Note: You should set this to something, otherwise it will default to ByPassword, which is both non-descriptive and too common.

AuthType should be set to Basic, since we are using Basic HTTP Authentication. Other possibilities for NCSA HTTPd 1.5 are PEM, PGP, KerberosV4, KerberosV5, or Digest. These other types of authentication will be discussed later.

In this example, only the method GET is restricted using the LIMIT directive. To limit other methods (particularly in CGI directories), you can specify them separated by spaces in the LIMIT directive. For example:

<LIMIT GET POST PUT>
require user pumpkin
</LIMIT>

If you only use GET protection for a CGI script, you may be finding that the REMOTE_USER environment variable is not getting set when using METHOD="POST", obviously because the directory isn't protected against POST.

Create the password file /otherdir/.htpasswd

The easiest way to do this is to use the htpasswd program distributed with NCSA HTTPd. Do this:

htpasswd -c /otherdir/.htpasswd pumpkin

Type the password -- pie -- twice as instructed.

Check the resulting file to get a warm feeling of self-satisfaction; it should look like this:

pumpkin:y1ia3tjWkhCK2

That's all. Now try to access a file in directory turkey -- your browser should demand a username and password, and not give you access to the file if you don't enter pumpkin and pie. If you are using a browser that doesn't handle authentication, you will not be able to access the document at all.

Multiple Usernames/Passwords

If you want to give access to a directory to more than one username/password pair, follow the same steps as for a single username/password with the following additions:

Add additional users to the directory's .htpasswd file.

Use the htpasswd command without the -c flag to add additional users; e.g.:

htpasswd /otherdir/.htpasswd peanuts
htpasswd /otherdir/.htpasswd almonds
htpasswd /otherdir/.htpasswd walnuts

Create a group file.

Call it /otherdir/.htgroup and have it look something like this:

my-users: pumpkin peanuts almonds walnuts

... where pumpkin, peanuts, almonds, and walnuts are the usernames.

.htaccess file in the directory to look like this:

AuthUserFile /otherdir/.htpasswd
AuthGroupFile /otherdir/.htgroup
AuthName ByPassword
AuthType Basic

<Limit GET>
require group my-users
</Limit>

Note that AuthGroupFile now points to your group file and that group my-users (rather than individual user pumpkin) is now required for access.

That's it. Now any user in group my-users can use his/her individual username and password to gain access to directory turkey.

Prepared Examples

Following are several examples of the range of access authorization capabilities available through Mosaic and NCSA HTTPd. The examples are served from a system at NCSA.

Simple protection by password.

For More Information

General questions may be addressed to info@brandx.net or support@brandx.net.

Brand X free websites are do-it-yourself and are provided without support. If you have a free website and want us to support it we will charge. That's the only way we can keep them free.

Historical note: This documentation is adapted from the original NCSA password documentation which is part of the site related to NCSA Mosaic and NCSA HTTPd. That documentation is designed for early versions of httpd, which formed the basis for the modern Apache server. We have adapted this by removing references to obsolete software. Very little else has changed.