NAME

User::Simple - Simple user sessions management

SYNOPSIS

$usr = User::Simple->new(db => $db,
                         [tbl => $user_table],
                         [durat => $duration],
                         [debug => $debug],
                         [adm_level => $level]);

$ok = $usr->ck_session($session);
$ok = $usr->ck_login($login, $passwd, [$no_sess]);
$ok = $usr->set_passwd($new_pass);
$usr->end_session;

$name = $usr->name;
$login = $usr->login;
$id = $usr->id;
$session = $usr->session;
$level = $usr->level;
$ok = $usr->is_admin;

DESCRIPTION

User::Simple provides a very simple framework for validating users, managing their sessions and storing a minimal set of information (this is, a meaningful user login/password pair, the user's name and privilege level) via a database. The sessions can be used as identifiers for i.e. cookies on a Web system. The passwords are stored as MD5 hashes (this means, the password is never stored in clear text).

User::Simple was originally developed with a PostgreSQL database in mind, but should work with any real DBMS. Sadly, this rules out DBD::CSV, DBD::XBase, DBD::Excel and many other implementations based on SQL::Statement - The user table requires the driver to implement primary keys and NOT NULL/UNIQUE constraints.

The functionality is split into two modules, User::Simple and User::Simple::Admin. This module provides the functionality your system will need for any interaction started by the user - Authentication, session management, querying the user's data and changing the password. Any other changes (i.e., changing the user's name, login or level) should be carried out using User::Simple::Admin.

CONSTRUCTOR

In order to create a User::Simple object, call the new argument with an active DBI (database connection) object as its only argument:

$usr = User::Simple->new(db => $db, [tbl => $table], [durat => $duration],
                         [debug => $debug], [adm_level => $level]);

Of course, the database must have the right structure in it - please check User::Simple::Admin for more information.

The tbl parameter is the name of the table where the user information is stored. If not specified, it defaults to 'user_simple'.

durat is the number of minutes a user's session should last. Its default is of 30 minutes.

debug is the verbosity level of the debugging messages - The default is 2, it accepts integers between 0 and 5 (higher means more messages). Messages of high relevance (i.e. the database failing to reflect any changes we request it to make) are shown if debug is >= 1, regular failure messages are shown if debug >= 3, absolutely everything is shown if debug == 5. Be warned that when debug is set to 5, information such as cleartext passwords will be logged as well!

adm_level gives us an extra way to tell if a user has administrative privileges - The users with a level under the number specified here will be seen as unprivileged, and those whose level is equal or higher than it will be treated as administrative users. The user level assigned to a user does not mean anything for User::Simple, but might be used inside your application. If adm_level is not specified, it will default to 1 (meaning that regular users' level is only 0, and any positive integer is an administrative user, as traditional in Perl's truth management). Please note (explanation follows below) that using adm_level and the is_admin method is deprecated in favor of directly querying $usr->level, and will be dropped in the future.

SESSION CREATION/DELETION

Once the object is created, we can ask it to verify that a given user is valid, either by checking against a session string or against a login/password pair::

$ok = $usr->ck_session($session);
$ok = $usr->ck_login($login, $passwd, [$no_sess]);

The optional $no_sess argument should be used if we do not want to modify the current session (or to create a new session), we want only to verify the password matches (i.e. when asking for the current password as a confirmation in order to change a user's password). It will almost always be left false.

To end a session:

$ok = $usr->end_session;

To verify whether we have successfully validated a user:

$ok = $usr->is_valid;

QUERYING THE CURRENT USER'S DATA

To check the user's attributes (name, login and ID):

$name = $usr->name;
$login = $usr->login;
$id = $usr->id;

To change the user's password:

$ok = $usr->set_passwd($new_pass);

USER LEVEL / ADMINISTRATIVE ACCESS

To check for the user level (or simply to check if the user has administrative access) (again, see User::Simple::Admin for further details):

$level = $usr->level;
$ok = $usr->is_admin;

Please note that User::Simple will only tell your application whether a user has administrative access (that is, $usr->is_admin is true, or $usr->level is equal or larger than adm_level. The is_admin method is for integration to your system, and does not mean that the user can access the functionality of User::Simple::Admin.

Yes, this last note takes away part of the nice simplicity of User::Simple, and that is not a good thing. This is still a very young module, but has already some systems depending on its way of working. Consider is_admin as deprecated, support for it will be dropped in the future.

DEPENDS ON

Date::Calc

Digest::MD5

SEE ALSO

User::Simple::Admin for administrative routines

TO DO

This module still requires a decent test suite. In order for it to become automatic, we need to be able to operate without a real RDBMS, i.e., with DBD::CSV.

The is_admin, adm_level and related infrastructure feels like a kludge, and cries to be removed. As for now, a simple warning about it being deprecated will do.

I would also like to separate a bit the table structure, allowing for flexibility - This means, if you added some extra fields to the table, provide an easy way to access them. Currently, you have to reach in from outside User::Simple, skipping the abstraction, to get them.

Besides that, it works as expected (that is, as I expect ;-) )

AUTHOR

Gunnar Wolf <gwolf@gwolf.org>

COPYRIGHT

Copyright 2005 Gunnar Wolf / Instituto de Investigaciones Económicas UNAM This module is Free Software, it can be redistributed under the same terms as Perl.