Authentication By User-Defined Usernames and Passwords or Groups

If you wish to authenticate users by user-defined usernames and passwords or groups, then you must follow these steps:

Create a password file that will contain the usernames and passwords for the protected area using the htpasswd(1) command. If the file does not exist, you can use the “-c” option to create it. For example:

% htpasswd -c /eecs/home/example/private/webpasswd joe

This would prompt you to create a web password for user “joe” and create a new password file called “webpasswd”. If you have already created the password file, and just want to add another user, do not use the “-c” option, as this will overwrite the existing file. Instead just use:

% htpasswd /eecs/home/example/private/webpasswd joe

The password file should not be located in a directory that is served by the web server. However, it must be a file that the web server has permission to access.

Ensure that the web server can read the password file. For example:

% chmod o+x /eecs/home/example
% chmod o+x /eecs/home/example/private
% chmod o+r /eecs/home/example/private/webpasswd

CAUTION: Other users on the system will also be able to read the password file. The passwords are encrypted, but this does not mean they are safe.

If you would like to authenticate based on user-defined groups, you must create a group file (eg. /eecs/home/example/private/webgroups) that assigns users from the above step to groups. The file will look like this:

students: joe sally
faculty: bob ruth
everyone: joe sally bob ruth

Here, users joe and sally are in the students group, users bob and ruth are in the faculty group, and everyone is in the everyone group.

If you created a groups file, ensure that the web server can read the file:

% chmod o+x /eecs/home/example
% chmod o+x /eecs/home/example/private
% chmod o+r /eecs/home/example/private/webgroups

CAUTION: Other users on the system will also be able to read the groups file.

In the directory you wish to protect, create a .htaccess file with the following contents:

AuthType Basic
AuthName "Name of Web Area You Are Protecting"
AuthUserFile /eecs/home/example/private/webpasswd

If you wish to restrict access to ALL user-defined accounts, add:

Require valid-user

If instead, you wish to restrict access to specific user-defined accounts, add for each user:

Require user <user>

For simplicity, you can also add all users on one line:

Require user <user1> <user2> ... <userN>

If you wish to restrict access to user-defined groups, you must let Apache know the name of the group file:

AuthGroupFile /eecs/home/example/private/webgroups

Now, for each group, add:

Require group <group>

Again, for simplicity, you can list all the groups on one line:

Require group <group1> <group2> ... <groupN>

If you only care about group membership alone (eg. all user-defined users who are in group “students”), then you only need to add a “Require group” directive, and you can skip “Require user” altogether.

If you only care about group alone, then you only need to add a “Require group” directive. In this case, you don't need “Require user”.

By default, only one of the conditions needs to be met to provide access, so if you were to add:

Require valid-user
Require group students

… then ANY valid user-defined user would be allowed in, or, any user who is in group students. If you want to just allow in user-defined users who are in group students, then include only the “Require group students” line. Alternatively you can use a “RequireAll” block like this:

<RequireAll>
  Require valid-user
  Require group guest
</RequireAll>

Check file permissions on your .htaccess file and directory permissions on all directories leading up to your .htaccess file.

At a minimum, your .htaccess file must be readable by the web server, which runs as user “www”:

% chmod o+r .htaccess

CAUTION: This will enable other users on the system to also read your .htaccess file

You will also need to ensure that all directories up to your .htaccess file are accessible by the web server. For example, if your .htaccess file is /eecs/home/example/www/.htaccess:

% chmod o+x /eecs/home/example
% chmod o+x /eecs/home/example/www