NAME
Authen::Users
DESCRIPTION
General password authentication using DBI-capable databases. Currently supports MySQL and SQLite databases.
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 qw(:SQLite);
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 user VARCHAR(30) User name password VARCHAR(60) Password, as SHA1 digest fullname VARCHAR(40) Full name of user email VARCHAR(40) User email question VARCHAR(120) Challenge question answer VARCHAR(80) Challenge answer creation VARCHAR(12) Internal use: row insertion timestamp modified VARCHAR(12) Internal use: row modification timestamp 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);
- user
-
Scalar. User name.
- password
-
Scalar. SHA1 digest of user's password.
- fullname
-
Scalar. The user's 'real' or full name.
-
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
-
Returns the last database error, if any.
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.