HTTP Authentication Setup - A Quick-Step Guide

Introduction

This document started out as some text notes from when I first tracked down a simple way to configure HTTP Authentication. For some reason, simple instructions were not easy to find -- at least not when I went looking (Admittedly that was quite some time ago).

The first public version of this document was a Qdig Help forum posting. (The original version is more specific to securing Qdig's admin.php script.) Hopefully this will save you some time. If you think this guide can be improved, let me know.

These are just quick and simple instructions. Consult the Apache Manual (1.3, 2.0) and the PHP Manual if you need more detailed information.

Simple HTTP-Auth Setup

Use the following steps to password-protect a directory and all of its subdirectories using HTTP authentication (.htaccess / .htgroups / .htpasswd). You can also protect individual files in a directory -- see below.

Step 1) Create a .htaccess file:

The special file .htaccess is a text file that contains per-directory "configuration directives" for a directory and all subdirectories in the tree below it. This document is about directives for access control to files, but there are directives for other purposes as well. Most people probably won't have a .htaccess file to start with. If one exists, you can add lines that one.

Note: It's possible your server's configuration may need to be adjusted in order for your .htaccess directives to take effect in the directory.

In the directory you want to protect (for this example we'll assume this will be the /home/someuser/public_html/somdirectory/ directory), create a text file called .htaccess with contents similar to this:

 AuthUserFile /home/someuser/public_html/somdirectory/.htpasswd
 AuthGroupFile /home/someuser/public_html/somdirectory/.htgroups
 AuthName "Secure Area"
 AuthType Basic
 require group editors

Step 2) Create a .htgroups file:

From the Apache manual:

...An authentication group is, as you would expect, a group name associated with a list of members. This list is stored in a group file, which should be stored in the same location as the password file, so that you are able to keep track of these things.

The format of the group file is exceedingly simple. A group name appears first on a line, followed by a colon, and then a list of the members of the group, separated by spaces...

Here is a /home/someuser/public_html/somdirectory/.htgroups file for our example setup:

 editors: jack jill

Step 3) Create a .htpasswd file using the htpasswd(1) command:

 htpasswd -nmb jack bucket >>.htpasswd
 htpasswd -nmb jill pail >>.htpasswd

or, if you don't want the passwords in your command history, you can type them in at a prompt:

 htpasswd -nm jack >>.htpasswd
 htpasswd -nm jill >>.htpasswd

Note: If you run the command twice for the same user there will be two lines in the .htpasswd file for that user. In that case, only first will be recognized. To change a user's password, edit the .htpasswd file and delete the old password, then add the new one.

Step 4) Set permissions if necessary.

 chmod 644 .ht*

Step 5) Test and celebrate.

Files in your directory should now be accessible only by the users in your group.

Improving On The Basic Setup

You should keep your .htpasswd and .htgroups files somewhere outside your web document tree. Here are steps to create a directory and move them there:

 mkdir -p /home/someuser/htaccess
 mv .htpasswd /home/someuser/htaccess
 mv .htgroups /home/someuser/htaccess

Change the AuthUserFile and AuthGroupFile in your .htaccess file to reflect the new path to .htpasswd and .htgroups:

 AuthUserFile /home/someuser/htaccess/.htpasswd
 AuthGroupFile /home/someuser/htaccess/.htgroups

Protecting Specific Files

If you only want to protect a specific file or files, you can easily do so. To protect only the file "admin.php" change the .htaccess file to the following, which presumes you moved the files outside the web document tree as specified above:

 AuthUserFile /home/someuser/htaccess/.htpasswd
 AuthGroupFile /home/someuser/htaccess/.htgroups
 AuthName "Secure Area"
 AuthType Basic
 <Files admin.php>
  require group editors
 </Files>

For Qdig users, make sure you set $this->use_authentication to FALSE in admin.php.

Group-less Configuration

Here are simple group-less examples if you don't want to use groups.

In place of step one, in the directory you want to protect (again assuming /home/someuser/public_html/somdirectory/), create a text file called .htaccess with contents similar to this:

 AuthUserFile /home/someuser/public_html/somdirectory/.htpasswd
 AuthName "Secure Area"
 AuthType Basic
 require valid-user

Skip to step 3 and generate a password or two.

 htpasswd -nmb jack bucket >>.htpasswd
 htpasswd -nmb jill pail >>.htpasswd

That will protect a directory using a .htpasswd file in your web document tree.

Here's a slight more advanced example where you've placed the .htpasswd file safely outside your web document tree and you're protecting only one file, admin.php. This is a group-less version of the example in "Protecting Specific Files" above:

 AuthUserFile /home/someuser/htaccess/.htpasswd
 AuthName "Secure Area"
 AuthType Basic
 <Files admin.php>
  require valid-user
 </Files>

Again, be sure to set permissions if necessary (e.g. with chmod 644 .ht* ) and Qdig users should set $this->use_authentication to FALSE in admin.php.

That's it! I've tested the steps outlined in this guide several times and I believe they're error-free. If you think this guide can be improved in some way, let me know.

– Hagan Fox