Restricting Access to Web Pages Published on Computer Systems Operated by Academic Computing Services

It is possible to restrict access to Web documents published on systems operated by ACS. The following is a description of methods for restricting access to certain files or directories. Access can be restricted to individuals, groups, or domains. Note that this method does NOT prevent other users on your system from accessing your Web documents, it only restricts people trying to access your documents via the Web.

Background

When a file request is made by a Web browser (sometimes called a client) such as Netscape Navigator, the request goes to a server program on the machine that stores the file. The server determines, among other things, the types and locations of files that can be returned to the browser. While the configuration of this server is determined and maintained by an administrative organization (in this case ACS), there are means for each individual user who has an account on the server machine to restrict access to his or her documents using "dynamic configuration" options.

The dynamic configuration options that are available depend on the particular server being used to deliver documents. All public ACS machines (FALCON, EAGLE, RAVEN, LARK, and PEOPLE) use Apache server software. This method involves creating a file, called .htaccess that contains dynamic configuration commands.  The .htaccess file is in effect for the directory in which it resides and all sub-directories under that directory unless there is a .htaccess file within a sub-directory.  In other words, the dynamic configurations contained in a .htaccess file "trickle down" to the sub-directories below it.

Each time the server receives a request to access a file, it first searches for a .htaccess file to determine what kind of access control to apply. If, for example, the .htaccess file indicates that access to the file requires a password, the server requests a password from the browser, which, in turn, displays a password request to the user. The user enters the password and the browser returns it to the server for evaluation.

Before You Start

1. In order to carry out the UNIX commands shown in the examples in this document, you must know how to access your multiuser system account via a telnet session. If you are unfamiliar with this process, please refer to BetterTelnet (Mac users) or QVT-Term (PC Users) and Eagle and Falcon (Mac and PC users).
2. You must also be familiar with one of the text editors on the multiuser systems such as Emacs, vi, or Pico. For help using Pico or Emacs, refer to Pico or Basic Emacs, respectively.
3. This document assumes you have already created a subdirectory called public_html in the home directory of your account for purposes of storing your Web documents. You must have a public_html directory before proceeding. If you do not, please see Publish Your Web Page for instructions on creating this directory.
4. If you have not yet logged into your multiuser account using telnet, do so now.
5. Some of the commands require that you enter your full path to a given directory. This information precedes the $ prompt after you log in. It will look something like:

   falcon:/homeb/imajhawk $

Make note of the home directory in which your account resides (e.g., /homeb in this example). You will need this for the commands that require a full path name.

Restricting Access to One or More Users

The basic steps, detailed below, are:

1. Create a directory for the password file.
2. Create the password file.
3. Create a .htaccess file.

Create a directory for the password file

The usernames and passwords that you want visitors to use to gain access to your site must be contained in a separate file located in a directory outside of your public_html directory. You can give this directory any name you choose. Create this directory as follows:

1. If your $ prompt is not currently displaying your home directory (e.g., /homeb/imajhawk $) enter cd at the current prompt. This returns you to your home directory.
2. At the $ prompt enter mkdir directoryname (Note that directoryname can be any name that you choose, e.g., secret or passwords). This creates the directory that you have specified.
3. At the $ prompt enter chmod 755 directoryname. Replace directoryname with the name you chose for your new directory in step 2. This allows the server access to this directory.

Create the password file

This step creates a file containing the username(s) and password(s) that allow access to your site. The filename will be .htpasswd. The items shown in italics must be supplied by you, as described in each step.

1. From the $ prompt enter the following command:

   htpasswd -c ~/passwddir/.htpasswd nameforuser

   Replace passwddir with the name of the directory you created in the Create a directory for the password file section above. Replace nameforuser with the name you want one or more users to use to access your site. Note: This username is not related to any e-mail username (login name). You supply whatever username you want.

   The htpasswd command creates the file called .htpasswd and puts it in passwddir. It then prompts you for the password (twice) that visitors to your site must use to gain access and then encodes the password before placing it in .htpasswd. The actual entry structure in the .htpasswd file will be of the form: username: encrypted_password.

   The -c option in this command causes the file .htpasswd to be created.

   Add additional usernames and passwords

   To add additional usernames and passwords to your .htpasswd file, from the $ prompt, enter:

   htpasswd ~/passwddir/.htpasswd anotherusername

   Replace passwddir with the name of the directory you created in the Create a directory for the password file section above. Replace anotherusename with the name you want one or more users to use to access your site. Note: This username is not related to any e-mail username (login name).

   Repeat as necessary. Otherwise, proceed to Step 2.

2. From your $ prompt enter: chmod 644 ~/passwddir/.htpasswd
   Replace passwddir with the name of the directory you created in Create a directory for the password file. This allows the server access to .htpasswd.

Create a .htaccess file

When the server receives a request to provide a file, it first checks to see if access to that file's directory has been restricted. If such restrictions are in place, information about them is contained in a file called .htaccess. The .htaccess file tells the server what type of access restrictions you want and where to find the file containing the authorized usernames and passwords.

1. Move to the directory for which you want to restrict access. This can be the public_html directory (effectively restricting access to your entire site) or any sub-directory within public_html. To change to a directory, enter the following from the $ prompt:
   cd ~/public_html/directoryname

   Replace directoryname with the name of the directory to which you want to change.  To see a list of your current sub-directories within public_html, enter the following from the $ prompt:
   ls -l ~/public_html

2. Start a text editor such as Emacs, vi, or Pico and open a blank (empty) document.
3. Enter the following lines, replacing the text in italics as explained below.

   AuthUserFile /homex/imajhawk/passwddir/.htpasswd
AuthGroupFile /dev/null
AuthName "WebSiteName"
AuthType Basic
require user username


   The first line of this example, AuthUserFile, tells the server to find the information about the passwords in the file named .htpasswd which is located in passwddir. Change the following:

   1. Change the x in homex to reflect the correct path to your home directory.
   2. Change imajhawk to your multiuser system account login name.
   3. Change passwddir to the name you chose for your password directory in Create a directory for the password file.

   The second line designates the group file. In this example there is no group file. The /dev/null is standard UNIX for "this file doesn't exist".

   WebSiteName appears as part of the message on the password prompt displayed by the browser when a visitor tries to access your site. Therefore, it should be something meaningful such as History Department or Michael's Homepage. The message prompt that the visitor sees will then look something like: Enter username for History Department at falcon.cc.ukans.edu. NOTE: if you are creating the .htaccess file on RAVEN (i.e. www.ukans.edu), PEOPLE, or LARK then you should enclose the AuthName in double-quotes (e.g. AuthName "History Department").

   For most purposes AuthType should be Basic.

   The require user username line tells the server that only the visitors who supply username with the correct password should receive the file. Replace username with a username from your .htpasswd file.  To allow for multiple usernames, add additional usernames to this line as in this example:
      require user username1 username2

   Or, if you wish to allow any user listed in your .htpasswd file access to your pages you can use the following require line instead:
      require valid-user

4. Save the file with the name .htaccess and close your editor.
5. The .htaccess file needs 644 access privileges. To change this enter: chmod 644 .htaccess from the $ prompt of the directory containing .htaccess.

You must create a .htaccess file in every sub-directory of public_html for which you want to specify access restrictions.   If you want to restrict access to your entire site, place the .htaccess  file in your public_html directory and the restrictions will be in effect for every sub-directory under public_html.   However, it is only necessary to have one .htpasswd file containing all of the possible usernames and passwords. Access to a given sub-directory is then restricted to those users listed in the .htaccess file in effect for that sub-directory.

Restricting Access to a Sub-Group of Users

Before you can restrict access to a group, you must first create a password directory and a password file. Instructions for doing this are in the section on Restricting Access to One or More Users.

The basic steps, detailed below, are:

1. Create the group file.
2. Create the .htaccess file.

Create (or edit) the group file

This step helps you create groups of users from among those users listed in your .htpasswd file.

1. Move to your password directory. From the $ prompt, enter: cd passwddir. Replace passwddir with the name of the password directory you created in Create a directory for the password file.
2. Start a text editor such as Emacs, vi, or Pico and open a blank (empty) document.
3. Enter a line of the form:
   groupname: user1 user2 user3

   For example,
   club-officers: John Karen Michelle

   User1, user2, etc. must be usernames that exist within your .htpasswd file. See Create the password file for more information.
   If you already have a .htgroup file and want to create another sub-group, simply add another line as shown in this step.

4. Save the file with the name .htgroup and close your editor.
5. From your $ prompt enter: chmod 644 ~/passwddir/.htgroup
   Replace passwddir with the name of the dirctory you created in Create a directory for the password file. This gives the server software access to .htgroup.

Create (or edit) the .htaccess file

When the server receives a request to provide a file, it first checks to see if access to that file's directory has been restricted. If such restrictions are in place, information about them is contained in a file called .htaccess. The .htaccess file tells the server what type of access restrictions you want and where to find the file containing the authorized usernames and passwords.

1. Move to the directory for which you want to restrict access. This can be the public_html directory (effectively restricting access to your entire site) or any sub-directory within public_html. To change to a directory, enter the following from the $ prompt:

   cd ~/public_html/directoryname

   Replace directoryname with the name of the directory to which you want to change.

2. Start a text editor such as Emacs, vi, or Pico and open a blank (empty) document.
3. Enter the following lines, replacing the text in italics as explained below.

   AuthUserFile /homex/imajhawk/passwddir/.htpasswd
AuthGroupFile /homex/imajhawk/passwddir/.htgroup
AuthName "WebSiteName"
AuthType Basic
require group groupname


   The first line of this example, AuthUserFile, tells the server to find the information about the passwords in the file named .htpasswd which is located in passwddir. Change the following:

   1. Change the x in homex to reflect the correct path to your home directory.
   2. Change imajhawk to your multiuser system account login name.
   3. Change passwddir to the name you chose for your password directory in Create a directory for the password file.

   The second line designates the group file. Again, change the following:

   1. Change the x in homex to reflect the correct path to your home directory.
   2. Change imajhawk to your multiuser system account login name.
   3. Change passwddir to the name you chose for your password directory in Create a directory for the password file.

   WebSiteName appears as part of the message on the password prompt displayed by the browser when a visitor tries to access your site. Therefore, it should be something meaningful such as "History Department" or "Michael's Homepage". The message prompt that the visitor sees will then look something like: Enter username for History Department at falcon.cc.ukans.edu. NOTE: if you are creating the .htaccess file on RAVEN (i.e. www.ukans.edu), PEOPLE, or LARK then you should enclose the AuthName in double-quotes (e.g. AuthName "History Department").

   For most purposes AuthType should be Basic.

   The require user groupname line tells the server that only the visitors who supply a username and corresponding correct password from the list of users in groupname will be accepted. Replace groupname with the name of a group from your .htgroup file. (See Create (or edit) the group file for more info.) To allow for multiple groups, add additional group names to this line as in this example:
      require user groupname1 groupname2

4. Save the file with the name .htaccess and close your editor.
5. From the $ prompt of the directory containing .htaccess, enter: chmod 644 .htaccess.

This gives the server software access to .htaccess. You must create a .htaccess file in every sub-directory of public_html for which you want to specify access restrictions. However, it is only necessary to have one .htpasswd and one .htgroup file containing all of the possible usernames, passwords, and group definitions. Access to a given sub-directory is then restricted to those users listed in the .htaccess file within that sub-directory.

Restricting Access by Domain

You can also set up your .htaccess file to allow or deny users from specific domains. This involves using the numerical Internet addess (i.e., IP address) or the registered domain name (e.g., .ukans.edu) of the location you want to allow or deny.

IP Address Example

For example, you may want to deny anyone outside of the University of Kansas access to your directory.  In this example the numerical Internet address of the domain "University of Kansas-Lawrence & Edwards Campuses"  (129.237) is used, rather than the mnemonic address (domain name), to ensure that computers without a registered mnemonic address (such as most campus lab machines) will be granted access. The following example .htaccess file shows how to do this.

AuthUserFile /dev/null
AuthGroupFile /dev/null
AuthName "WebSiteName"
AuthType Basic
order deny,allow
deny from all
allow from 129.237


WebSiteName appears as part of the message on the password prompt displayed by the browser when a visitor tries to access your site. Therefore, it should be something meaningful such as "History Department" or "Michael's Homepage". The message prompt that the visitor sees will then look something like: Enter username for History Department at falcon.cc.ukans.edu. NOTE: if you are creating the .htaccess file on RAVEN (i.e. www.ukans.edu), PEOPLE, or LARK then you should enclose the AuthName in double-quotes (e.g. AuthName "History Department").

Important note: the order deny,allow line tells the server to first deny and then allow. In other words, first the server will deny from all, then it will allow from 129.237. If the two lines deny from all and allow from 129.237 are switched, the end result will be the same.

Domain name example

To keep all users from a certain location from accessing a document, the process is very similar. In the following case, any user from the Internet domain netscape.com is denied entry.

AuthUserFile /dev/null
AuthGroupFile /dev/null
AuthName "ExampleDenyFromNETSCAPE"
AuthType Basic
order allow,deny
allow from all
deny from .netscape.com
    

Changing Access Restrictions

1. Changing Access Restrictions for a User
2. Changing Access Restrictions for a Sub-Group
3. Changing Access Restrictions for a Directory

Changing Access Restrictions for a User

You can change access restrictions in two ways: Adding or deleting users listed in your .htaccess file(s) and/or adding or deleting users and passwords from your .htpasswd file.

To change which users can access your site (directory):

1. Move to the directory for which you want to change access.
2. Edit the .htaccess file, using Emacs, vi, or Pico.
3. Add more require user username lines and/or delete the require user username lines for those users who should no longer have access.

   Note: The usernames that you add must be included in the .htpasswd file.

   To change entries in your password file and to add more users and passwords to your .htpasswd file, see Add additional usernames and passwords.

   To delete a user, open the .htpasswd file in a Unix editor such as Emacs or Pico and delete the line containing the username you no longer want to have.
   Note: It is not possible to simply change the password for a user. To do so, first delete the user from the .htpasswd file and then follow the instructions in Adding additional usernames and passwords.

Changing Access Restrictions for a Sub-Group

1. Move to the directory for which you want to change access.
2. Edit the .htaccess file, using Emacs, vi, or Pico.
3. Add more require group groupname lines and/or delete the require group groupname lines for those groups that should no longer have access.

   Note: The groupnames that you add must be included in the .htgroup file.

Changing Access Restrictions for a Directory

If you want to alter the current access restrictions, follow the steps in Changing Access Restrictions for a User above. If you want to remove all access restrictions for a given directory, simply delete its .htaccess file as follows.

From the $ prompt within the directory for which you want to remove restrictions, enter:

rm .htaccess

Related Training from ACS

Academic Computing Services offers free training on UNIX, HTML, Web page design and more. See http://www.cc.ukans.edu/acs/training/ for complete details.

Getting Additional Help

Technical assistance for the University of Kansas community is available from:

Jeff Long
(785) 864-0457
long@ku.edu

Computer Center Help Desk
(785) 864-0200

Original documentation by Michael Gregory, June 24, 1997
Revised by Carine Ullom, May 5, 1998
Revised by Jeff Long, July 30, 2001
© Academic Computing Services