Sometimes, it is necessary to authenticate by system usernames and passwords or groups along with a few additional user-defined usernames and passwords or groups. This can be easily setup.

Create a password file that will contain the user-defined 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. If you have already created the password file, do not use the “-c” option, as this will overwrite the existing file. Instead just use:

% htpasswd

The password file should not be located in a directory that is served by the webserver. However, it must be a file that the webserver 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 above, ensure that the web server can read the file like this:

% 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:

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

If you will be authenticating based on user-defined groups add:

AuthGroupFile /eecs/home/example/private/webgroups

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

Require valid-user

If instead, you wish to restrict access to specific users, add for each user:

Require user <userid>

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

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

If you wish to restrict access to specific system groups, add for each group:

Require unix-group <group>

If you wish to restrict access to specific user-defined groups, add:

Require group <group>

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

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

If you only care about group alone, then you only need to add a “Require unix-group” or “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 guest
Require unix-group faculty

… then all user-defined users or system users would be permitted.

If you wish to restrict access to specific system groups OR user-defined groups, simply remove the “Require valid-user” line.

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 /cs/home/example/www/.htaccess:

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

In order to better protect system usernames and passwords, the SSLRequireSSL directive in your .htaccess file only permits access to PAM authentication over https. Please DO NOT remove this directive. Access a secure web site, /cs/home/example/www/secure like this:

https://www.eecs.yorku.ca/~example/secure

… and not like this:

http://www.eecs.yorku.ca/~example/secure

Note: Access to your secure page over http will yield a “Forbidden” error message.

(optional) If you would like to automatically redirect http accesses to your page to the secure https version, add the following code to the .htaccess file that is in the directory above the one you are protecting:

ErrorDocument 403 /cgi-bin/pamredirect.cgi

That is, if you are protecting /eecs/home/example/www/secure, you would place the line above into /eecs/home/example/www/.htaccess and not /eecs/home/example/www/secure/.htaccess.

This code takes advantage of the fact that an error 403 (Forbidden) is produced when a user accesses your secure page via http. It redefines the error handler for “Forbidden” to a CGI script that will redirect the user to the https version of your page. Since the line must appear in the .htaccess file above the directory you are protecting, you cannot use this redirection trick to protect your main web page (eg. /eecs/home/example/www), but you can use it to protect any directories beneath.

Notes:

• Access to your web page for user-defined accounts will be slower since every request will attempt to authenticate first against a system username, fail, and then against the user-defined username.

• A utility, mkhtaccess is available for helping you build your .htaccess file. See the mkhtaccess page for details.

• Full details on Apache authentication can be found in the Apache authentication documentation.

• Always be careful when using your system username and password for accessing web pages. Only use it on sites that you trust.