Authen::Users
Authen::Users
Authen::Users - DBI Based User Authentication
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.
After several web sites were written which required ongoing DBI or .htpassword file tweaking for user authentication, it seemed we needed a default user password database that would contain not only the user name and password but also such things as the information needed to reset lost passwords. Thus, this module, designed to be as much as possible a drop-in for your website authorization scripting needs.
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);
Create a new Authen::Users object.
my $authen = new Authen::Users(dbname => 'Authentication');
Defaults are dbname => SQLIte, authen_table => authentication, create => 0 (off), digest => SHA1.
my $authen = new Authen::Users( dbtype => 'SQLite', dbname => 'authen.db', create => 1, authen_table => 'authen_table', digest => 512 );
my $authen = new Authen::Users( dbtype => 'MySQL', dbname => 'authen.db', dbpass => 'myPW', authen_table => 'authen_table', dbhost => 'mysql.server.org', digest => 256 );
Takes a hash of arguments:
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)
user VARCHAR(30)
password VARCHAR(60)
fullname VARCHAR(40)
email VARCHAR(40)
question VARCHAR(120)
answer VARCHAR(80)
creation VARCHAR(12)
modified VARCHAR(12)
pw_timestamp VARCHAR(12)
gukey VARCHAR (46)
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.
Add a user to the database. Synonym: user_add.
The arguments are as follows:
$authen->add_user($group, $user, $password, $fullname, $email, $question, $answer) or die $authen->error;
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 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();
$authen->update_user_password($group, $user, $password) or die "Cannot update password for group $group and user $user: $authen->errstr";
Update the password.
$authen->update_user_fullname($group, $user, $fullname) or die "Cannot update fullname for group $group and user $user: $authen->errstr";
Update the full name.
$authen->update_user_email($group, $user, $email) or die "Cannot update email for group $group and user $user: $authen->errstr";
Update the email address.
$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.
$authen->delete_user($group, $user) or die "Cannot delete user in group $group with username $user: $authen->errstr";
Delete the user entry.
$authen->count_group($group) or die "Cannot count group $group: $authen->errstr";
Return the number of entries in group $group.
$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.
$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.
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.
$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.
$authen->get_user_email($group, $user) or die "Cannot retrieve email of $user in group $group: $authen->errstr";
Return the user email entry.
$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.
$authen->get_password_change_time($group, $user) or die "Cannot retrieve password timestamp for $user in group $group: $authen->errstr";
There is a timestamp associated with changes in passwords. This may be used to expire passwords that need to be periodically changed. The logic used to do password expiration, if any, is up to the code using the module.
print $auth->errstr();
Returns the last database error, if any.
print $auth->error;
Returns the last class internal error message, if any; if none, returns the last database DBI error, if any.
$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.
$auth->is_in_table($group, $user);
True if $user in group $group is already in the database.
$auth->validate($group, $user, $password);
True if the item is a valid entry; internal use
On installation, "make test" may fail if Perl support for MySql or SQLite is installed, but the database itself is not running or is otherwise not available for use by the installing user. MySql by default has a 'test' database which is required under "make test." "Forcing" installation may work around this.
William Herrera (wherrera@skylightview.com)
Questions, feature requests and bug reports should go to wherrera@skylightview.com
Copyright (C) 2004, 2008 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.