Web: Using Basic Authentication

The Apache web server in use at Communications allows access to files to be controlled using login names and passwords. This mechanism is called basic authentication in web terminology. The steps involved are quite simple:

Create a password file, containing login names and passwords.
Create a .htaccess file.

Let's consider these steps in turn.

1. Create a password file

Create a file in which you will store login names of those authorized to access your files, and their encoded passwords. Put the file anywhere it will be accessible to the web server. You could, for example, put it in your top-level web directory. We will call this file `example.passwd' (but you can use any name). An easy way of generating this file is by using the htpasswd command from the UNIX shell. Enter the password when prompted (it will not echo). The command prints a brief usage message if invoked without arguments.


     % htpasswd
     Usage: htpasswd [-c] passwordfile username
     The -c flag creates a new file.

     % htpasswd -c example.passwd joeuser
     Adding password for joeuser.
     New password:
     Re-type new password:

     % cat example.passwd
     joeuser:u.7ZRafnjoeS6

     % htpasswd example.passwd sueuser
     Adding user sueuser
     New password:
     Re-type new password:

     % cat example.passwd
     joeuser:u.7ZRafnjoeS6
     sueuser:XgYgQDm8Itpe2

2. Create a `.htaccess` file

Create a file called `.htaccess' in the directory in which you wish to control access. (To create this file, you may use any text editor. For example, you may use the simple self-explanatory text editor pico for this purpose. To do this, you would type the command `pico .htaccess' at the UNIX shell. Before doing so, please read the instructions below.)

The basic format of the contents of the .htaccess file is:


     authtype basic
     authname authdomain
     authuserfile pathname
     require valid-user

The first line above `authtype basic' will always appear as shown.

The second line beginning with `authname' specifies the authentication domain. This is any arbitrary name selected by you. The exact name is not important. If you have more than one directory in which authentication is being done, you can use the same authname for all of them. Then a user who has entered a login name and password for any one of these directories will be able to access the others without retyping his login name and password. A good choice for authname is your login name.

The third line beginning with `authuserfile' must be the absolute pathname of the password file, so the web server knows where to find it. By "absolute" pathname we mean the pathname beginning with a slash "/" that would be used by any of the standard system programs (such as "ls", "vi", 'cat", etc.) to access the file. If you place this file in your top web directory, then its pathname will be of the form /xx/home/USER/www/FILE, where xx is some two-character combination, USER is your login name, and FILE is the filename of your password file.

The "pwd" command while you are logged into the UNIX shell will help you find this. Or, when you are logged in for ftp, ask your ftp client to show you the current directory pathname. Make sure the pathname begins with /xx/home. If you see a longer name, e.g., /mauve/xxx/home, /violet/xx/home, or something similar, then omit the initial /mauve or /violet, or other string, which is caused due to filesystems being mounted across the network. Use only the part beginning with /xx/home/.

To double-check, make sure that you can access the password file by the resulting pathname. E.g., see if you can list it with the "ls" command from the UNIX shell, using the pathname you found above. Then use this pathname in the authuserfile line in your .htaccess file.

Example

Suppose a user `joeuser' has a password file called `example.passwd'. User joeuser finds that his top web directory pathname is /mf/home/joeuser/www. To this he appends his password file name, giving him the absolute pathname of his password file as: `/mf/home/joeuser/www/example.passwd' . This is the pathname that he will insert into his .htaccess file in the authuser line.

The fourth line beginning with `require' specifies which users may access the contents of the directory. If any user who is listed in the password file will be granted access, specify `require valid-user' as above. If only specific uses will be granted access, list them like this: `require user <name> <name> ...' where <name> is a username.

Following the above procedures, we can create the .htaccess file for user joeuser to look like this:


     authtype basic
     authname basicauth-example
     authuserfile /mf/home/joeuser/www/example.passwd
     require valid-user

Almost done!

We are almost done. As a final step, make sure your password file is readable by the web server. To ensure this, simply make sure the file is world-readable. The following command suffices:


     chmod a+r example.passwd

That's it!

We have placed the example authentication files, created as above, in the following directory:


     /mf/home/joeuser/www

Feel free to look in these files and adapt them for your own needs. To access joeuser's web files, use this login name and password:


     login:    joeuser
     password: a.b.C.D

and go to: http://www.rahul.net/joeuser/.

One final hint

For best security, we recommend putting the password file somewhere where it cannot be downloaded via the web. One way of doing this is to put the password file in a directory that is itself protected by a .htaccess file, and to put no passwords in the password file for that directory. For example, you could have a subdirectory called passwords within your web directory, and you could have a .htaccess file within that subdirectory that protects access to that subdirectory.

One final warning

The use of basic authentication protects your files from unauthorized access via the web. However, other users with logins on the same machine can read your files via the UNIX shell.

To top howto page
To a2i communications home page