University of Southern California

ITS Information Technology Services

Basic Authentication

There are two methods of controlling access:

These methods can be used separately or together.

If you wish to limit access by IP address (e.g., allow access only from the USC campus), you only need to read the section entitled "Allow/Deny Access." If you would like to password-protect your documents, you need to read this entire document, including the "Allow/Deny" section.

About .htaccess

You can control access to any of your web document directories by placing the server directives in a .htaccess file for that directory. This page provides a description of how to use the .htaccess file and the related htpasswd program for access control. The .htaccess page has more information on the .htaccess file and its other uses.

Allow/Deny Access

There are four directives used to control access - order, deny, allow, and require.

  1. order
    affects the order in which the allow and deny operations are executed. The arguments of the order directive are separated by a comma with NO SPACE between them. How you arrange allow and deny in the order directive depends on the intent of your access file. In order to only allow access from certain computers, you first need to deny access to all, and in order to deny access from specific computers, you must first allow access from all computers.

    FOR EXAMPLE: If the intent of your .htaccess file is to allow only users from USC, your .htaccess file would look like this:

    order deny,allow
    deny from all
    allow from 128.125.
    allow from 68.181.

    (128.125 and 68.181 are the IP addresses for the University Park and Health Sciences Campuses. 207.151 is the IP address for the wireless network. Depending on the nature of your pages, you may also want to give access to the USC Information Sciences Institute (128.9.) and the LAC+USC Medical Center (163.40.):

    order deny,allow
    deny from all
    allow from 128.125.
    allow from 68.181.
    allow from 207.151.
    allow from 128.9.
    allow from 163.40.

    The other option with order is mutual-failure which means that any computer listed on the allow list is allowed and any computer listed on the deny list is denied, and then any computer that isn't on either list is automatically denied.

  2. deny
    used to deny access to the web directory. The arguments can be specified in a variety of ways:

    full IP address
    deny from
    partial IP addresses (for denying access to subnets)
    deny from 128.125.141
    or keyword all
    deny from all

  3. allow
    used to allow access to the web directory. The arguments can be specified the same way as in the deny directive.

  4. require
    used to restrict access to specific users and groups.

    require user username
    require group groupname

    Here username refers to a specific user in a password file. The groupname refers to a group that has been created in a group file. Please see Username/Password Access for information on creating users and groups.

IMPORTANT: Be sure to include a hard return after the last line of the .htaccess file or else you may experience problems with your access file.

Different access for a subdirectory

The access restrictions in a .htaccess file will be applied to all subdirectories UNLESS you include a different .htaccess file in that subdirectory. The best way to show this to you would be with an example.

Let's say that you have a main directory called 'foo' which you want to be only accessible to computers in the USC domain, but there is a subdirectory called 'bar' which you want to be accessible to everyone. There is another subdirectory called 'test' which you want to be only accessible to USC computers. You would need to create two files.

First, you would need a file 'foo/.htaccess' that would look like the following:

order deny,allow
deny from all
allow from 128.125.

Then, you would need a file 'foo/bar/.htaccess' that would look like the following:

allow from all

You would not need a .htaccess file in the directory 'foo/test' because the restrictions from the 'foo' directory would automatically be applied to that directory as well.

Username/Password Access

Setting up password protection requires two steps:

  1. Create a password file using the htpasswd program
  2. Create (or modify) an .htaccess file to work with the password file

Using the htpasswd program

The htpasswd program is a utility for creating usernames and passwords in order to require authentication when accessing a web directory.

The usage for the htpasswd program is as follows:

htpasswd [-c] passwordfile username

The -c flag is used to create a new password file. If your password file already exists, do not use the -c flag because it will overwrite your previous password file with a new one.

passwordfile refers to the pathway and name of the file that you wish to store the password information in, and username is the name of the user you want to create or change the password for. The password file may be named anything you want, but most commonly it is named .htpasswd. For example, if you wanted to create a password file named .htpassword in a directory '/www/foo' for a user named 'tommy', you would type the following:

htpasswd -c /www/foo/.htpasswd tommy

You would then be prompted to enter a new password for tommy and confirm that password. The password that you input is then encrypted and stored in the password file that you've specified. The information is encrypted so that it will not be easy for someone to read the password file and get another user's password.

Adding users and changing passwords

Once you've created a password file in a directory, you can add new users using the htpasswd program. For example, to add the user 'simpson', you would type the following:

htpasswd /www/foo/.htpasswd simpson

Make sure you don't use the -c flag because the password file already exists. The -c flag is used ONLY when a password file is being created. You could use this same method to change the password for 'tommy', by typing:

/www/bin/htpasswd /www/foo/.htpasswd tommy

The htpasswd program does not provide a means of removing users from your password file. If you want to deny a former user access, the simplest way is to use the htpasswd program to enter a new password for that user.

Choosing passwords

Please do not use real UNIX passwords as your web passwords. The http passwords are sent across the network unencrypted, so they're vulnerable to sniffing. Although we support other protocols (e.g. telnet) that send unencrypted passwords, the http protocol sends the passwords much more often -- the http password is sent with every request (in contrast, telnet sends the password only once, at the beginning of the session). At USC, the htpasswd command has been modified not to accept the UNIX password of the person running the command, or of the user whose password is being created/modified (if that user has a UNIX password).


b>The .htaccess file

To restrict a directory to any user listed in the .htpasswd file just created, you should create a .htaccess file containing:

AuthName "restricted stuff"
AuthType Basic
AuthUserFile /www/foo/.htpasswd

require valid-user

The first directive, AuthName, specifies a realm name for this protection. Once a user has entered a valid username and password, any other resources within the same realm name can be accessed with the same username and password.

The AuthType directive tells the server to use the Basic method for authentication (currently the only method available).

AuthUserFile tells the server the location of the .htpasswd file created by htpasswd. A similar directive, AuthGroupFile, can be used to tell the server the location of a groups file (see below).

Require valid-user tells the server that any username/password pair in the .htpasswd file can be used to access this directory. However, it is possible to limit access to only certain users:

require user tommy simpson

would only allow users tommy and simpson (with correct passwords) to access the directory. Another user in the .htpasswd file would be denied access even though he used a valid password.

Creating User Groups

The last example could have also been completed by creating a group that contained the two users that you wanted to allow directory access. To do this all you need to do is create a file that contains the group name and lists the name of the people in that group. The one catch is that all of the users that are specified in your group file must be also in your password file. For example, you could create a file called .htgroup which contains the following:

mygroup: tommy simpson

And the .htaccess file would look like this:

AuthUserFile /www/foo/.htpasswd
AuthGroupFile /www/foo/.htgroup
AuthName GroupAccess
AuthType Basic

require group mygroup

Using Combinations of Users and Groups

Users and Groups can be used in conjunction with one another as well. In the previous example, if I wanted to allow access to the user 'allen' without adding that user to mygroup, I could do it this way:

AuthUserFile /www/foo/.htpasswd
AuthGroupFile /www/foo/.htgroup
AuthName GroupAccess
AuthType Basic

require group mygroup
require user allen

The directory would then be accessible for 'tommy', 'simpson', and 'allen'.

Combining Different Types of Restriction

You can use different types of access restrictions in combination as well. For instance, you could restrict access based on domain name or IP address as well as requiring a certain username and password. For this next example, let's say that I want to restrict my directory to only allow access the USC campus, but I also want to require the users 'tommy' or 'allen'. Here's what the .htaccess file would look like in that case:

AuthUserFile /www/foo/.htpasswd
AuthName "ByDomainAndUser"
AuthType Basic

order deny,allow
deny from all
allow from 128.125.
require user tommy allen
require user allen

Conversely, you can allow access to the USC campus, AND to users outside of USC who have valid usernames and passwords. This is accomplished using the "satisfy any" directive:

AuthType Basic 
AuthUserFile  /www/foo/.htpasswd
AuthName "byDomainOrUser" 

order deny,allow
deny from all 
allow from 128.125.
require valid-user 
satisfy any 

Protecting Your Files

The .htpasswd file must be readable by the web server, or else the server won't be able to authenticate any of your users. However, this makes the password file vulnerable to someone grabbing the file and attempting to decrypt the passwords it contains.

Likewise, the files you're trying to protect also must be readable by the web server. But if you make them world-readable, it means that anyone with a server account can also see them.

Using standard UNIX file permissions, this poses quite a dilemma. However, through the use of Access Control Lists (ACLs), you can make files readable only by you and the web server by specifying read access for user webfoot, the web server.

Final Note

One final note on using user and group authentication: Once a user has visited a restricted directory with a browser and has entered a valid password, the authentication will remain valid until the user has quit out of the browser. The browser will only ask for a password one time until it has been quit.

You might therefore want to let users of your restricted directories know that they should quit their browsers when they are done to prevent unwanted people from gaining access to your restricted directories. Authentication is not saved with a bookmark file however, so if you bookmark a file in a restricted directory, you will still need to send your username and password the first time you go to that page in a session.

Last updated:
March 08, 2010

Web Publishing Documentation

The use of all USC computing resources is governed by the USC Computing Policies.