NAME

LibWeb:: - Sessions management for libweb applications

SUPPORTED PLATFORMS

BSD, Linux, Solaris and Windows.

REQUIRE

LibWeb::CGI
LibWeb::Crypt
LibWeb::Database
LibWeb::Digest

ISA

LibWeb::Core

SYNOPSIS

  use LibWeb::Session;
  my $s = new LibWeb::Session();

  my ($user_name, $user_id) = $s->get_user();

#or

  my ($user_name, $user_id)
      = $s->get_user( -is_update_db => 1 );

ABSTRACT

This class manages session authentication after the remote user has logged in.

The current version of LibWeb::Session is available at

   http://libweb.sourceforge.net

Several LibWeb applications (LEAPs) have be written, released and are available at

   http://leaps.sourceforge.net

TYPOGRAPHICAL CONVENTIONS AND TERMINOLOGY

Variables in all-caps (e.g. MAX_LOGIN_ATTEMPT_ALLOWED) are those variables set through LibWeb's rc file. Please read the LibWeb::Core manpage for more information. All `error/help messages' mentioned can be found at the LibWeb::HTML::Error manpage and they can be customized by ISA (making a sub-class of) LibWeb::HTML::Default. Please see the LibWeb::HTML::Default manpage for details. Method's parameters in square brackets means optional.

DESCRIPTION

METHODS

get_user()

Check to see if the viewing Web browser has logged in by checking expiration time, IP and MAC in the authentication cookie, and return the user name and the user ID if it passes all the authentication checks.

Params:

  [ -no_auth=>, -mac_mismatch=>, -ip_mismatch=>,
    -expired=>, -is_update_db=> ]

Pre:

-no_auth is a CODE reference for callback if the viewing browser does not return an authentication cookie.
-mac_mismatch is a CODE reference for callback if the authentication cookie has been tampered with.
-ip_mismatch is a CODE reference for callback if the IP in the authentication cookie does not correspond to the IP address of the viewing browser.
-expired is a CODE reference for callback if the authentication cookie is expired.
-is_update_db is either 1 or 0 (default). Use this to indicate whether this is the first login check. This parameter should be 1 in order to update database's NUM_LOGIN_ATTEMPT when a user first logged in.

Post:

Retrieve authentication cookies from the viewing Web browser,
All -no_auth, -mac_mismatch, -ip_mismatch and -expired default to the following actions if you do not provide the callbacks:
- Nullify and delete all authentication cookies resided on the viewing Web browser,
- send an alert e-mail to ADMIN_EMAIL,
- log that event in FATAL_LOG,
- redirect the remote user to the login page (LM_IN), and
- abort the current running program.
Check to see If cookie values are null/zero, call -no_auth if no authentication cookie is retrieved,
Check to see If MAC matches, call -mac_mismatch if not,
Check to see if If IP matches, call -ip_mismatch if not,
update database: Set NUM_LOGIN_ATTEMPT to 0 and call -expired if the login has expired,
If the retrieved cookie passes all the above authentication checks, set database's NUM_LOGIN_ATTEMPT to LOGIN_INDICATOR if parameter -is_update_db is defined and is equal to 1. This helps indicate that the user is online (currently login),
and finally return an array (user name and uid) in plain text.

Note:

USER_LOG_TABLE.NUM_LOGIN_ATTEMPT != 0 && != LOGIN_INDICATOR means there were several attempts to login but unsuccessful solely because incorrect password were entered by the remote user. You need to re-flush database's USER_LOG_TABLE.NUM_LOGIN_ATTEMPT to 0 manually after receiving the alert e-mail if this value == MAX_LOGIN_ATTEMPT_ALLOWED; otherwise, the user will never be able to sign into your site even he/she enters the correct password afterwards.

DEPRECATED METHODS

is_login()

Note:

This method is deprecated as of LibWeb-0.02. You are encouraged to use get_user() instead. is_login() is mainly for backward compatible with client codes written using LibWeb-0.01.

Params:

  [ is_just_logged_in ]

Pre:

Parameter `is_just_logged_in' is either 1 or undef. This is to indicate whether this is the first login check. This parameter should be defined in order to update database's USER_LOG_TABLE.NUM_LOGIN_ATTEMPT when user first logged in; possibly in the first script invoked after the user has been authenticated.

Post:

Retrieve authentication cookies from client Web browser,
if cookie values are null/zero, send an alert e-mail to ADMIN_EMAIL and redirect the remote user to the login page (LM_IN),
if MAC mis-match (this means possible spoofing from remote host), send an alert e-mail to ADMIN_EMAIL and redirect the remote user to the login page (LM_IN),
if IP mis-match (this means possible spoofing from remote host), send an alert e-mail to ADMIN_EMAIL and redirect the remote user to the login page (LM_IN),
login is expired if expiration time reached. Update database: set USER_LOG_TABLE.NUM_LOGIN_ATTEMPT to 0, send an alert e-mail to ADMIN_EMAIL and redirect the remote user to the login page (LM_IN),
nullify and delete all cookies reside on client Web browser immediately if any of item 2, 3, 4 or 5 happens. Send an alert e-mail to ADMIN_EMAIL and redirect the remote user to the login page (LM_IN),
if client has officially logged in and none of item 2, 3, 4 or 5 happens, set USER_LOG_TABLE.NUM_LOGIN_ATTEMPT to LOGIN_INDICATOR if parameter `is_just_logged_in' is defined. This helps to indicate that the user is online (currently logged in), and
finally return an array (user name and uid) in plain text.

Note: USER_LOG_TABLE.NUM_LOGIN_ATTEMPT != 0 && != LOGIN_INDICATOR means there were several attempts to login but unsuccessful solely because incorrect password were entered by the remote user. You need to re-flush NUM_LOGIN_ATTEMPT to 0 manually after 24 hours (no rigorous reason why it should be 24 hours) of receiving the alert e-mail if this value == MAX_LOGIN_ATTEMPT_ALLOWED.

AUTHORS

Colin Kong (colin.kong@toronto.edu)