Password Protection with .htaccess & .htpasswd

John Urbanek

Target Audience

This explanation/tutorial/documentation is intended for those unfamiliar with the mechanisms required for basic password authentication. The methods and directives presented here only encompass the tip of the iceberg when it comes to configuring Apache. Do not expect to become an expert reading this tutorial alone. For more information see the links at the end of this document.

Introduction

Protecting content on the web is something that most savvy users will have to do at one point or another. Whether the content is personal or professional, there comes a time when that content must only be seen by "authorized" eyes. The Apache web server ( that daemon that serves up your marvelous content ) allows a user to configure two files to facilitate this very purpose. Those files are .htaccess and .htpasswd.

.htaccess
The .htaccess file is a simple text file placed in the directory you want the contents of the file to affect. The rules and configuration directives in the .htaccess file will be enforced on whatever directory it is in and all sub-directories as well. In order to password protect content, there are a few directives we must become familiar with. One of these directives in the .htaccess file ( the AuthUserFile directive ) tells the Apache web server where to look to find the username/password pairs.
.htpasswd
The .htpasswd file is the second part of the affair. The .htpasswd file is also a simple text file. Instead of directives, the .htpasswd file contains username/password pairs. The password will be stored in encrypted form and the username will be in plaintext.

.htaccess In Depth

Like mentioned earlier, the .htaccess file is a simple text file. It can be created using a text editor. Any text editor will do. On a *nix machine vi and pico should be available to you. The file could even be created in Windows with an ASCII text editor like Notepad and then uploaded using FTP or some similar mechanism.

You will want to put the .htaccess file in the directory you wish to protect. Remember that all sub-directories will be protected as well. Figure 1 represents a very simple recommended format for an .htaccess file whose sole purpose is to protect directories. Use the following as a template for your .htaccess file and review the directives below for more information and specific changes.

AuthUserFile /usr/uj/jurbanek/.htpasswd
AuthType Basic
AuthName "My Files"
Require valid-user

Figure 1 - Recommended .htaccess Format; A sample .htaccess file.

AuthUserFile Directive
The AuthUserFile directive in the .htaccess file tells the Apache web server where the username/password pairs are going to be kept. In other words, it tells Apache where the .htpasswd file is going to be located. This is the directive that "links" the .htaccess and .htpasswd files. After the text AuthUserFile be sure to put the FULL path to the .htpasswd file. Relative paths can be used, but they can get quite complicated since they are relative to the ServerRoot. Do not use relative paths, use full paths when specifying the location of the .htpasswd file. Further discussion about the .htpasswd file and where to put it will occurr later. If you know where you are going to put the .htpasswd file, then you can adjust the path now. Below are a few examples of the AuthUserFile directive.
AuthUserFile /home/jurbanek/.htpasswd
AuthUserFile /alpha3usr/uj/jurbanek/.htpasswd
AuthUserFile /usr/uj/jurbanek/www/.htpasswd
AuthUserFile /home/jurbanek/htdocs/files/.htpasswd
AuthUserFile /home/jurbanek/public_html/.htpasswd
Figure 2 - AuthUserFile directive examples.
AuthType Directive
The AuthType directive is not one you have to worry about. Basic is the only type of authentication that is widely used. There are others, such as Digest authentication, but do not worry about them. Leave this line as it is.
AuthType Basic
Figure 3 - AuthType directive.
AuthName Directive
The AuthName directive is used to indicate the collective title of the documents that are to be protected. The name specified will usually appear in the authentication window that the client will see when they are prompted to type in their username and password. If the name you would like to use contains spaces, be sure to enclose the entire name in double-quotes. Below are a few examples AuthName.
AuthName "My Files"
AuthName Protected
AuthName "John's Secret Documents"
Figure 4 - AuthName directive examples.
Require Directive
The Require directive tells Apache which users/groups are able to access the content being protected. There are a few special keywords that can be used. One of the keywords is valid-user. This keyword tells Apache to grant access to anyone specified in the AuthUserFile directive, (the .htpasswd file). If you wish to specify a few users in the .htpasswd you can omit the valid-user and enter their username as specified in the .htpasswd file. See a list of examples below.
# This is a comment, it is ignored by Apache due to the # character
Require valid-user
Require john
Require dave jane

# The following line does not make semantic sense, do not do this
Require valid-user dave
Figure 5 - Require directive examples.

.htpasswd In Depth

Like mentioned earlier, the .htpasswd is a simple text file, however it should very rarely be editted by hand. There is a special program on a *nix machine that is designed to manipulate the .htpasswd file on your behalf. The name of this program is htpasswd. There are 2 fundamental ways to use htpasswd. The first way is to create a new .htpasswd file and add a username/password pair to the file. The second way is to add a username/password pair to an existing .htpasswd file.

To create a new .htpasswd file in /usr/uj/jurbanek/ with username john, the following command would be used.

# '-c' stands for 'create'.  Only to be used when creating a new .htpasswd file.
# You will be prompted for the password you would like to use after entering the command below.

htpasswd -c /usr/uj/jurbanek/.htpasswd john

Figure 6 - htpasswd command example. Note the '-c' is only used when creating a new .htpasswd file.

To add dave to an existing .htpasswd file located in /usr/uj/jurbanek/ the following command will be used.

# Notice there is no '-c' since the file exists already, we just want to add 'dave'
# You will be prompted for the password you would like to use after entering the command below.

htpasswd /usr/uj/jurbanek/.htpasswd dave

Figure 7 - htpasswd command example, adding a user to a .htpasswd file.

Sample .htpasswd File

Below is a sample .htpasswd file that contains users john and dave

john:n5MfEoHOIQkKg
dave:9fluR/1n73p4c

Figure 8 - Sample .htpasswd file.

Notes on .htpasswd files.

Troubleshooting

More Information