Authenticate.pm

NAME

Authenticate.pm - Perl module for Apache authentication.

DESCRIPTION

Authenticate.pm is a Perl module that provides management tools for user authentication on the Apache server. It contains methods for managing password files, group files, and .htaccess files. It utilizes the database authentication modules built into Apache and Perl to store password files and group files as databases rather than flat text files. This is useful for large user bases where searching flat files is prohibitively slow. Authenticate.pm also includes methods for generating flat text files if the server is not configured for database files.

EXAMPLES

Editing password and group files:

If you want to edit a password or group file, you must call the member function setup with the file to be edited, the function to be executed, and the arguments to be sent to that function. This is because setup manages the overhead of opening and closing the database. If you call the password and group member functions directly, they won't work since the database won't have been initialized. This may be changed in future versions so that other member functions can be accessed directly.

For example, if you want to add a user/password combination to a password file, you would use the following syntax:

use Authenticate;

...

Authenticate->setup($passwdDBFile, "addPasswdUser", $username, $passwd1, $passwd2);

Note that you don't have to use Authenticate->setup(...), you could just use setup(...) and it would have the same effect. I have chosen this syntax because it helps me to keep track of which module the subroutines are being called from.

To change the password you would use the following:

Authenticate->setup($passwdDBFile, "changePasswd", $username, $oldPasswd, $passwd1, $passwd2);

To add a user to a group in a groupfile you would use the following:

Authenticate->setup($groupDBFile, "addGroupUser", $username, $newGroups);

When you want to save the group file to a flat file, use the following:

Authenticate->setup($groupDBFile, "saveGroupFile", $flatFile);

And for the password file:

Authenticate->setup($passwdDBFile, "savePasswdFile", $flatFile);

Editing .htaccess files:

**Note: The exact structure of .htaccess files is different for database authentication vs. flat file authentication. Keep this in mind when choosing which function to use to create your .htaccess file.

To create an .htaccess file to be used with database authentication, use the following syntax:

Authenticate->createDBHtaccess($baseDir, $dir, $authType, $authName, $authUserFile, $authGroupFile, $require, $satisfy);

To create an .htaccess file to be used with flat file (regular) authentication, use the following syntax:

Authenticate->createHtaccess($baseDir, $dir, $authType, $authName, $authUserFile, $authGroupFile, $require, $satisfy);

Note that for creating .htaccess files, you do not need to call setup because there is no database to be opened and closed.

DEPENDENCIES

Uses modules CGI, CGI::Carp qw(fatalsToBrowser), and DB_File. The apache module mod_auth_db must be installed for database authentication to work. For instructions on installing mod_auth_db, click here.

CAVEATS

Since this module uses databases rather than flat files for data storage, it may be less efficient than flat file storage for small numbers of users (less than 100). This can be alleviated by converting to a flat file using the appropriate member function. The underlying storage mechanism will be a db file either way. Empirically, the efficiency difference seems too small to be noticeable in the sample application that uses Authenticate.pm for a small group of users.

METHODS

setup($dbFile, $command, @args) - Initializes the database with the data from $dbFile. Calls the subroutine $command. Closes the database, saving the database back into $dbFile.
Arguments:
  • $dbFile - database file (password file or group file)
  • $command - name of the subroutine to be called
  • @args - arguments to be passed to the subroutine $command

Password File Methods

**Note: These functions must be called via the member function setup so that the database is properly initialized. See Examples for, well, examples.

savePasswdFile($flatFile) - Saves database info to a flat password file so that the file can be used by the usual (non-database) apache authentication
Arguments:
  • $flatFile - file where flat password file is to be saved
addPasswdUser($username, $passwd1, $passwd2) - Adds user $username to password file with password $passwd1
Arguments:
  • $username - username to be added to password file
  • $passwd1 - first password
  • $passwd2 - repeated password
checkPasswd($username, $testpass) - Checks the password file to see if $testpass matches the password for $username.
Arguments:
  • $username - username to be checked
  • $testpass - password to be checked
changePasswd($username, $passwd1, $passwd2) - Changes the password for $username to $passwd1 assuming that $passwd1 matches $passwd2 and is at least 5 chars long.
Arguments:
  • $username - username whose password is to be changed
  • $passwd1 - new password
  • $passwd2 - repeated new password
changePasswdSecure($username, $oldPasswd, $passwd1, $passwd2) - Changes the password for $username to $passwd1 assuming that the $oldPasswd checks out and $passwd1 matches $passwd2 and is at least 5 chars long.
Arguments:
  • $username - username whose password is to be changed
  • $oldPasswd - old password (to be checked)
  • $passwd1 - new password
  • $passwd2 - repeated new password
changePasswdUsername($oldUsername, $newUsername) - Changes the username $oldUsername to $newUsername.
Arguments:
  • $oldUsername - old username to be changed
  • $newUsername - new username to replace old username
changePasswdUsernameSecure($oldUsername, $newUsername, $passwd) - Changes the username $oldUsername to $newUsername assuming that the $passwd checks out.
Arguments:
  • $oldUsername - old username to be changed
  • $newUsername - new username to replace old username
  • $passwd - old password (which will stay the same)
deletePasswdUser( $username) - Deletes user $username from the password file.
Arguments:
  • $username - username to be deleted from password file

Group File Methods

**Note: These functions must be called via the member function setup so that the database is properly initi alized. See Examples for, well, examples.

saveGroupFile($flatFile) - Saves database info to a flat group file so that the file can be used by the usual (non-database) apache authentication.
Arguments:
  • $flatFile - file where flat group file is to be saved
addGroupUser($username, $newGroups) - Adds the user to all of the groups in $newGroups. If groups don't exist, they are created. If the user is already a member of a group, the user is not added again and no error message is sent.
Arguments:
  • $username - username to be added
  • $newGroups - groups (separated by spaces) that the username to to
deleteUserAll($username) - Deletes a specified user from all groups within a specified group file.
Arguments:
  • $username - username to be deleted
deleteGroupUser( $username, $groups) - Deletes specified user from specified group in specified group(s).
Arguments:
  • $username - username to be deleted
  • $groups - $groups (separated by spaces) that the user is to be deleted from
changeGroupUsername($oldUsername, $newUsername, $groups) - Changes the username $oldUsername to $newUsername in the groups contained in $groups.
Arguments:
  • $oldUsername - old username to be replaced
  • $newUsername - new username to replace old username
  • $groups - groups where this change is to take effect
changeGroupName($oldGroupname, $newGroupname) - Changes old group name to new group name.
Arguments:
  • $oldGroupname - old group name to be replaced
  • $newGroupname - new group name to replace old group name

.htaccess File Methods

createDBHtaccess($path, $authType, $authName, $authUserFile, $authGroupFile, $require, $satisfy) - Creates .htaccess file designed to be used with a database password file in specified directory.
Arguments:
  • $path - Full path to .htaccess file
  • $authType - Authentication type being used. In this case, it will be set to Basic
  • $authName - The authentication realm or name
  • $authUserFile - The location of the password file
  • $authGroupFile - The location of the group file, if any
  • $require - The requirement(s) which must be satisfied in order to grant admission
  • $satisfy - Satisfy condition
createHtaccess($path, $authType, $authName, $authUserFile, $authGroupFile, $require, $satisfy) - Creates a regular (non-database) .htaccess file designed to be used with a flat password file in specified directory.
Arguments:
  • $path - Full path to .htaccess file
  • $authType - Authentication type being used. In this case, it will be set to Basic
  • $authName - The authentication realm or name
  • $authUserFile - The location of the password file
  • $authGroupFile - The location of the group file, if any
  • $require - The requirement(s) which must be satisfied in order to grant admission
  • $satisfy - Satisfy condition
editHtaccessField($path, $fieldName, $newVal) - Replaces the old value associated with a given field with the new value.
Arguments:
  • $path - Full path to .htaccess file
  • $fieldName - name of field to be edited
  • $newVal - new value to be associated with field
appendHtaccessField($path, $fieldName, $newVal) - Appends the new value to the end of a given field *if* the value is not already contained in the field.
Arguments:
  • $path - Full path to .htaccess file
  • $fieldName - name of field to be edited
  • $newVal - new value to be associated with field
cutHtaccessValue($path, $fieldName, $oldVal) - Removes the value from the given field, while leaving the rest of the field intact. For example, removing "sci" from "Require groups sci sci-werks" would result in "Require groups sci-werks"
Arguments:
  • $path - Full path to .htaccess file
  • $fieldName - name of field to be edited
  • $oldVal - new value to be associated with field

FILES

To be fully functional, needs to work with the following files:

BUGS

To report a bug, send mail to Jennifer Simpson at (simpson@cs.utah.edu)

ERROR HANDLING

Errors result in an error message being sent to the browser as well as the sever error log. Error conditions include:

SEE ALSO

Authenticate.pm

Design document for Authenticate.pm.

Demo pages which use this script :
Basic Demo
Download Wizard (XML/XSL written by Erik Jorgenson and integrated with Authenticate.pm)
User Authentication Manager (XML/XSL written by Erik Jorgenson and integrated with Authenticate.pm)

A good tutorial on basic Apache authentication:
Apache Authentication

AUTHORS

Jennifer Simpson (simpson@cs.utah.edu).

NOTES

If you use flat file authentication, keep in mind that you will need to use two files: a db file for database storage and a flat file for authentication. Both of these files contain the same information, but the db file is a binary database file and the flat file is just a regular text file. If you use database authentication, you don't need to have a flat file since you'll be using the db file directly for authentication. There won't be any file extensions on either of these files unless you specify them (i.e. passwords.db and passwords.txt) in the filename.