Tuesday, March 29, 2011

htpasswd Tutorial

If you would like to have a set of web pages that are protected, requiring a username/password to gain access, this tutorial will show you how to set it up. This is geared towards the Unix Apache httpd servers used on holly, lamar, and www.colostate.edu. If you are using another web server, you'll need to check that server's documentation to see how to do this.

Steps to Password-protect a Directory

First, create a subdirectory in your web area. For the sake of this tutorial, I have created the "protect" directory. Set the permissions on the directory so that the server has read/execute. I do this by using the local command chgrp-www to set the group to the www group. This is the group that the server runs under at Colorado State University for the lamar, holly and www servers. I have used the -sd flag which sets "set group id" for a directory. This will then force any files you create within the protect directory to the www group, so if you ftp files to this directory they will be automatically readable by the server but not by any other user on the system. I then cd into the protect directory.
cd ~ric/public_html
mkdir protect
chmod g+r,g+x,o-r,o-x protect
chgrp-www -sd protect
cd protect
Next you must create a .htaccess file inside the directory you want protected. You can use either the vi or pico editors on the supported systems mentioned above or ftp the file to this directory. If you are new to unix or know little about vi then I suggest you use the pico editor or ftp the .htaccess file. The command to edit with pico is "pico .htaccess". The .htaccess file should contain the following lines. The items inbold are things you will want to change depending on the location of the AuthUserFile and content of AuthName.
AuthUserFile /z/ric/secret/.htpasswd
AuthGroupFile /dev/null
AuthName "Ric's protected files"
AuthType Basic

<Limit GET>
require valid-user
</Limit>
The AuthName is what the user will see when they're prompted for a password - something to the effect of "Enter the username for Ric's Protected files". The AuthUserFile is location of the password file and should be not accessible with a url on the server for security reasons. This is a full unix path and the permissions should be set up like the "protect" directory using the chmod and chgrp-www commands above so the only one that can read this file is the owner and the server. To get the full path of a directory, cd to that directory and enter the command "pwd" to print the working directory path.Now you'll have to set up the password file. You'll need to use the htpasswd program. It is included with the Apache httpd server.
First cd to the directory that contains the password file. In this example the password file is called .htpasswd and is in the directory /z/ric/secret/ as indicated by the AuthUserFile file entry in the .htaccess file. For every username you want to add to the password file, enter the following. (the -c is only required the first time; it indicates that you want to create the .htpasswd file).

   cd
   mkdir secret
   cd secret
   htpasswd -c .htpasswd pumpkin
     [ you're prompted for the password for pumpkin]
     [ if you have other users enter the following. Don't use the -c]
   htpasswd .htpasswd user2
   htpasswd .htpasswd user3
Again, make sure the permissions are set up like the "protect" directory using the chmod and chgrp-www commands above so the only one that can read files in the "secret" directory is the owner and the server.Here is the protected page using the above setup to password protect this page. The username is "pumpkin" and password is "pie".


---------------------------------------------------------------------------------------------------------

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.

  • Format: username:encrypted_password
  • The username is case-sensitive. John and john are two different username's.
  • Location: It is a good idea to put the .htpasswd file outside of your web accessible documents. Try to keep it out of your htdocs, www, and public_html folders. This is a security measure. Most web servers are configured to not allow people to remotely view your .htpasswd file, but it never hurts to keep it out of the web tree.

Troubleshooting

  • Make sure that the path specified in AuthUserFile is the correct full path. This is a major cause of problems. If Apache cannot find the .htpasswd file, then all attempts will fail.
  • Make sure the permissions on the .htaccess and .htpasswd files are set so that Apache can read them.
    • chmod 0644 .htaccess
    • chmod 0644 .htpasswd
  • Other issues may be out of your control. Web administrators can lock down Apache so that it ignores all .htaccess files it encounters. This can be achieved with an AllowOverride None directive and option on the ServerRoot/DocumentRoot directories. If this is the case (.htaccess not allowed) you will have to kindly ask your web administrator to allow .htaccess files with authorization directives in your personal web directory. This can be achieved with AllowOverride AuthConfig directive and option.

More Information

Posted by at

No comments:

Post a Comment

Subscribe to: Post Comments (Atom)