NAME
XAO::DO::Web::IdentifyUser - class for user identification and verification
SYNOPSYS
Currently is only useful in XAO::Web site context.
DESCRIPTION
IdentifyUser class is used for user identification and verification purposes. In 'login' mode it logs a user in while in 'logout' mode, it logs a user out. In 'check' mode it determines the identification status of the user using cookies.
Possible user identification status are:
anonymous - user cannot be identified
identified - user has been identified
verified - user has recently been positively identified
The 'IdentifyUser' class takes the following parameters:
mode
Indicates how 'IdentifyUser' will be used. Possible values are
anonymous.path
Template to display if user has not been identified.
identified.path
Template to display if user has been identified, but not verified.
verified.path
Template to display if user has been identified.
hard_logout
If 'true' in logout mode, this parameter not only unverifies the user, but erases identification cookies too. The default is to retain identified status.
stop
Directive indicating that if a specified template is displayed, the remainder of the current template must not be displayed.
The 'IdentifyUser' class relies on some site configuration values. These values are available in the form of a reference to a hash obtained as follows:
my $config=$page->siteconfig->get('identify_user');where $page is a 'Page' object. The keys of such a hash correspond to the 'type' parameter of the 'IdentifyUser' class. An example of a $config hash with all required parameters is presented below:
customer => {
list_uri => '/Customers',
id_cookie => 'id_customer',
id_cookie_expire => 126230400, # (seconds) optional, default is 4y
user_prop => 'email', # optional, see below
pass_prop => 'password',
pass_encrypt => 'md5', # optional, see below
vf_key_prop => 'verify_key', # optional, see below
vf_key_cookie => 'key_customer', # optional, see below
vf_time_prop => 'latest_verified_access',
vf_expire_time => '600', # seconds
cb_uri => 'IdentifyUser/customer' # optional
}- list_uri
-
URI of users list (see XAO::FS and XAO::DO::FS::List).
-
Name of cookie that IdentifyUser sets to identificate the user in the future
-
Expiration time for the identification cookie (default is 4 years).
- user_prop
-
Name attribute of a user object. If there is no 'user_prop' parameter in the configuration it is assumed that user ID is the key for the given list.
- pass_prop
-
Password attribute of user object.
- pass_encrypt
-
Encryption method for the password. Available values are 'plaintext' (not encrypted at all, default) and 'md5' (MD5 one way hash encryption.
- vf_key_prop
-
The purpose of two optional parameters 'vf_key_cookie' and 'vf_key_prop' is to limit verification to just one computer at a time. When these parameters are present in the configuration on login success 'IdentifyUser' object generates random key and store it into user's profile anf create a cookie named according to 'vf_key_cookie' with the value of the generated key.
-
Temporary verifiction key cookie.
- vf_time_prop
-
Attribute of user object which stores the time of latest verified access.
- vf_expire_time
-
Time period for which user remains verified.
- cb_uri
-
URI of clipboard where IdentifyUser stores identification and verification information about user and makes it globally available.
EXAMPLE
Now, let us look at some examples that show how each mode works.
LOGIN MODE
<%IdentifyUser mode="login"
type="customer"
username="<%CgiParam param="username" %>
password="<%CgiParam param="password" %>
anonymous.path="/bits/login.html"
verified.path="/bits/thankyou.html"
%>LOGOUT MODE
<%IdentifyUser mode="logout"
type="customer"
anonymous.path="/bits/thankyou.html"
identified.path="/bits/thankyou.html"
hard_logout="<%CgiParam param="hard_logout" %>"
%>CHECK MODE
<%IdentifyUser mode="check"
type="customer"
anonymous.path="/bits/login.html"
identified.path="/bits/order.html"
verified.path="/bits/order.html"
%>METHODS
- check_mode (%)
-
Checks operation mode and redirects to a method accordingly.
- check ()
-
Checks identification/verification status of the user.
To determine identification status, first check clipboard to determine if there is such object present. If so, then that object identifies the user. If not, then check whether there is a identification cookie and if so, perform a search for object in database. If this search yields a positive result, the user's status is 'identified' and an attempt to verify user is made, otherwise the status is 'anonymous'.
Once identity is established, to determine verification status, first check the clipboard to determine if there is a 'verified' flag set. If so, then the user's status is 'verified'. If not, check whether the difference between the current time and the time of the latest visit is less than vf_expire_time property. If so, the user status considered 'verified', a new time is stored.
If optional 'vf_key_prop' and 'vf_key_cookie' parameters are present in the configuration then one additional check must be performed before changing status to 'verified' - the content of the key cookie and apropriate field in the user profile must match.
- display_results ($$;$)
-
Displays template according to the given status. Third optinal parameter may include the content of 'ERRSTR'.
- find_user ($;$)
-
Searches for the user in the list according to the configuration:
my $user=$self->find_user($config,$username); - login ()
-
Logs in user. Saves current time to vf_time_prop database field. Generates pseudo unique key and saves it value to vf_key_prop (optional). Sets identification cookies.
- logout ()
-
Logs out user. Resetting vf_time_prop database field and clearing identification cookie (for hard logout mode). Set user status to 'anonymous' (hard logout mode) or 'identified'.
EXPORTS
Nothing
AUTHOR
Copyright (c) 2001 XAO, Inc.
Andrew Maltsev <am@xao.com>, Marcos Alves <alves@xao.com>, Ilya Lityuga <ilya@boksoft.com>.
SEE ALSO
Recommended reading: