NAME

Authen::Users

DESCRIPTION

General password authentication using DBI-capable databases. Currently supports MySQL and SQLite databases. The default is to use a SQLite database to store and access user information.

This module is not an authentication protocol. For that see something such as Authen::AuthenDBI.

SYNOPSIS

use Authen::Users;

my $authen = new Athen::Users(dbtype => 'SQLite', dbname => 'mydbname');

my $a_ok = $authen->authenticate($group, $user, $password);

my $result = $authen->add_user( $group, $user, $password, $fullname, $email, $question, $answer);

METHODS

new

Create a new Authen::Users object:

my $authen = new Authen::Users( dbtype => 'SQLite', dbname => 'authen.db', create => 1, authen_table => 'authen_table' );

or,

my $authen = new Authen::Users( dbtype => 'MySQL', dbname => 'authen.db', dbpass => 'myPW', authen_table => 'authen_table', dbhost => 'mysql.server.org' );

Takes a hash of arguments:

dbtype

The type of database. Currently supports 'SQLite' and 'MySQL'. Defaults to SQLite.

dbname

The name of the database. Required for all database types.

authen_table

The name of the table containing the user data.

NOTE: If this is omitted, defaults to a table called 'authentication' in the database. If the argument 'create' is passed with a true value, and the authen_table argument is omitted, then a new empty table called 'authentication' will be created in the database.

The SQL compatible table is currently as follows:

groop VARCHAR(15) Group of the user =item user VARCHAR(30) User name =item password VARCHAR(60) Password, as SHA1 digest =item fullname VARCHAR(40) Full name of user =item email VARCHAR(40) User email =item question VARCHAR(120) Challenge question =item answer VARCHAR(80) Challenge answer =item creation VARCHAR(12) Internal use: row insertion timestamp =item modified VARCHAR(12) Internal use: row modification timestamp =item gukey VARCHAR (46) Internal use: key made of user and group--kept unique

For convenience, the database has fields to store for each user an email address and a question and answer for user verification if a password is lost.

create

If true in value, causes the named authen_table to be created if it was not already present when the database was opened.

dbpass

The password for the account. Not used by SQLite. Generally needed otherwise.

dbhost

The name of the host for the database. Not used by SQLite. Needed if the database is hosted on a remote server.

authenticate

Authenticate a user. Users may have the same user name as long as they are not also in the same authentication group. Therefore, the user's group should be included in all calls to authenticate the user by password. Passwords are stored as SHA1 digests, so the authentication is of the digests.

add_user

Add a user to the database.

The arguments are as follows:

$authen->add_user($group, $user, $password, $fullname, $email, $question, $answer);

group Scalar. The group of users. Used to classify authorizations, etc. User names may be the same if the groups are different, but in any given group the users must have unique names.

user

Scalar. User name.

password

Scalar. SHA1 digest of user's password.

fullname

Scalar. The user's 'real' or full name.

email

Scalar. User's email address.

question

Scalar. A question used, for example, for identifying the user if they lose their password.

answer

Scalar. The correct answer to $question.

Note: it is up to the user of the module to determine how the fields after group, user, and password fields are used, or if they are used at all.

update_user_all

Update all fields for a given group and user:

$authen->update_user_all($group, $user, $password, $fullname, $email, $question, $answer) or die "Could not update $user: " . $authen->errstr();

update_user_password

$authen->update_user_password($group, $user, $password) or die "Cannot update password for group $group and user $user: $authen->errstr";

Update the password.

update_user_fullname

$authen->update_user_fullname($group, $user, $fullname) or die "Cannot update fullname for group $group and user $user: $authen->errstr";

Update the full name.

update_user_email

$authen->update_user_email($group, $user, $email) or die "Cannot update email for group $group and user $user: $authen->errstr";

Update the email address.

update_user_question_answer

$authen->update_user_question_answer($group, $user, $question, $answer) or die "Cannot update question and answer for group $group and user $user: $authen->errstr";

Update the challenge question and its answer.

delete_user

$authen->delete_user($group, $user) or die "Cannot delete user in group $group with username $user: $authen->errstr";

Delete the user entry.

count_group

$authen->count_group($group) or die "Cannot count group $group: $authen->errstr";

Return the number of entries in group $group.

get_group_members

$authen->get_group_members($group) or die "Cannot retrieve list of group $group: $authen->errstr";

Return a reference to a list of the user members of group $group.

user_info

$authen->user_info($group, $user) or die "Cannot retrieve information about $user in group $group: $authen->errstr";

Return a reference to a list of the information about $user in $group.

user_info_hashref

my $href = $authen->user_info_hashref($group, $user) or die "Cannot retrieve information about $user in group $group: $authen->errstr"; print "The email for $user in $group is $href->{email}";

Return a reference to a hash of the information about $user in $group, with the field names as keys of the hash.

get_user_fullname

$authen->get_user_fullname($group, $user) or die "Cannot retrieve full name of $user in group $group: $authen->errstr";

Return the user full name entry.

get_user_email

$authen->get_user_email($group, $user) or die "Cannot retrieve email of $user in group $group: $authen->errstr";

Return the user email entry.

get_user_question_answer

$authen->get_user_question_answer($group, $user) or die "Cannot retrieve question and answer for $user in group $group: $authen->errstr";

Return the user question and answer entries.

errstr

$auth->errstr();

Returns the last database error, if any.

not_in_table

$auth->not_in_table($group, $user);

True if $user in group $group is NOT already an entry. Useful to rule out an existing user name when adding a user.

is_in_table

$auth->is_in_table($group, $user);

True if $user in group $group is already in the database.

BUGS

On installation, "make test" may fail if Perl support for MySql or SQLite is installed, but the database itself is not running, or is restricted from use by the installing user. MySQl by default has a 'test' database which is used by under "make test." Forcing installation may work around this.

AUTHOR

William Herrera (wherrera@skylightview.com)

SUPPORT

Questions, feature requests and bug reports should go to wherrera@skylightview.com

COPYRIGHT

Copyright (C) 2004 William Hererra.  All Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.