ABSTRACT

This class encapsulates user registrations of a VIP application.

Not every surfer of the VIP application is a registred user. Some may not be validated at all. Most surfers will validate with shibboleth or nethz. They will get a temporary VIP user registration when they login. This registration may be deleted after a few days by a cronjob, if the user registration does not have relations to other resources (like roles etc).

Users have the following attributes:

Ident
The ident is an internal datatype (a number). It never changes.

Firstname
The name is a nonempty ISO-8859-1 string of 2 to 255 character length.

Lastname
The name is a nonempty ISO-8859-1 string of 2 to 255 character length.

Email
Each registred user must have an email address. It is in standard computer readable format (RFC 822). I.e. gerber@id.ethz.ch

Nethz_ID
Optional, unique. The Nethz Username, when the surfer validates against the nethz system.

Nethz_NPID
Optional. The Nethz NPID (Person Identification), when the surfer validated against the nethz system.

Shibboleth_ID
Optional, unique. The shibboleth swissEduPersonUniqueID given when the surfer validates with shibboleth.

Shibboleth_PW
Optional password; Additional password that will be checked after timeout for Shibboleth users. It is stored in crypted form.

Shibboleth_PW_expires
Optional, UNIX time value; If set, it defines the time, after which the Shibboleth_PW must be changed by the user.

Vip_ID
Optional, unique. May be a username (recommended: UNIX conventions which are 2 to 8 lowercase ASCII letters or digits) or an email address in computer readable form (I.e. gerber@id.ethz.ch).

Vip_PW
Required password; when a Vip_ID (Loginname) is defined, this is the password that will be checked. It is stored in crypted form. Must be empty when no Vip_ID is defined.

Last Login
A UNIX time value (seconds since 1970-1-1 00:00:00) of the last login. Zero or NULL mean both 'no login yet'.

Last Action
A Unix time value of the last action of the user. An action is defined as the entry of his password.

Has Resources Flag
A Flag for the optimisation of cronjobs which clean up unused user registrations: a weekly job may calculate the flags value to 'yes', 'no' or '', which means unknown. A daily cronjob may select all users with Has_Resources_Flag 'no', and a Last_Action time > two days, check if they did not get any resources in the time since the weekly last run, and delete it or set his flag to 'yes'.

At least one of the IDs (Nethz_ID, Shibboleth_ID or Vip_ID) should be specified for every user.


SYNOPSIS

 use Users;
 $user = Users->find(-id=>$id);
 $string = $user->email();
 $string = $user->name();
 $user->update(-firstname=>$new_name, -shibboleth_id=>$new_id);


DESCRIPTION

Object Constructor

$user = Users->find( -id=>Ident );
$user = Users->find( -nethz_id=>nethz_username );
$user = Users->find( -shibboleth_id=>swissEduPersonUniqueID );
$user = Users->find( -vip_id=>identification );
Object constructor. The find method searches the DB and returns a object with the state as found at find method call time. If the desired user is not found, an empty object is returned - i.e. the result of a Users->create(). CGI programs may use the class method Users->select_dialog( ... ) to let the surfer select a user.

$user = Users->create( );
Creates an object in memory but not on the VIP database. Its content should be set with the $user->update()-method, which will update the VIP database as well, if the input checks pass. The first update should set at least the -firstname, -lastname and -email-attributes and one of the ID-attributes: -nethz_id, -shibboleth_id and/or -vip_id.

$aref = Users->get_object_list( ... );
Returns a refernce to an array of Users objects. Without arguments, all defined Users objects are returned. Arguments reduce this set; if more than one argument is given, a Users object must match all arguments to be included in the list.

Arguments:

validated_by=>'nethz'
validated_by=>'shibboleth'
validated_by=>'vip'
Include only users with an appropiate validation id (nethz_id, shibboleth_id or vip_id). Only one of the validated_by=> arguments may be passed.

email_like=>$string
Include only users with an email address ending on $string.

teacher_group_id=>0
Include only users who are members of a teacher group.

teacher_group_id=>id
Include only users who are members of teacher group id.

user_id=>id
Includes only user with id.

$aref = Users->get_id_list( ... );
Returns a refernce to an array of IDs of Users objects. Same Arguments as Users->get_object_list( ... )

Object Accessor Methods

The following methods return the current state of a user object:

$string = $user->email;
$string = $user->firstname;
$string = $user->has_resources;
Returns 'yes' or 'no' or an empty string meaning 'unknown';

$string = $user->id;
$time = $user->last_action;
Returns a UNIX time value (integer)

$string = $user->last_login;
Returns a HTML formatted string.

$string = $user->lastname;
$string = $user->nethz_id;
$string = $user->nethz_npid;
$string = $user->shibboleth_id;
$string = $user->shibboleth_pw;
Returns the crypted password.

$string = $user->shibboleth_pw_expires;
Returns a UNIX time value; Any false value means 'does not expire'.

$string = $user->vip_id;
$string = $user->vip_pw;
Returns the crypted password.

Object Modifier Method

($field, $errmsg) = $user->update( ... )
Updates the user (object state and data base permanent storage). Before any data is changed, all values are checked. If a check fails, the update will not change any data but return a list of two values: the name of the field and an error message. If all checks are ok, the update method will change the objects state in memory and on the VIP database and return undef. What will be updated is determinated by arguments as follows:
-firstname=>$string
ISO-8859-1 string. 2 to 255 characters long.

-lastname=>$string
ISO-8859-1 string. 2 to 255 characters long.

-last_action=>1
Sets the last action time to the current time.

-last_login=>1
Sets the last login time to the current time.

-has_resources =>'yes'
-has_resources =>'no'
-has_resources =>''
Sets has_resources to 'yes', 'no' or an empty string.

-has_resources =>'check'
Let the update method check if the user has any resources (roles or teacher group memberships) and set has_resources to 'yes' or 'no'.

-email=>$string
ISO-8859-1 string. 2 to 255 characters long. Standard format (RFC 822), i.e. theodor.gerber@id.ethz.ch. Each registred user should have an email address.

-nethz_id=>undef
-nethz_id=>$nethz_username
undef or '' means the user does not valiadte through nethz.

-nethz_npid=>undef
-nethz_npid=>$number
undef or '' may mean one of two things: the users npid is not known or he is not registred in nethz.

-shibboleth_id=>undef
-shibboleth_id=>$shibboleth_id
undef or '' means the user does not validate with shibboleth.

-shibboleth_pw=>undef
-shibboleth_pw=>$plaintext_password
A User who valiadtes with shibboleth, may have a password defined that will be checked after timeout. It may be empty. Otherwise a plain text password is expected. It must be at least 2 characters long. It is crypted and any later reference to it will return it crypted. There is no way to get it back in plain text.

-shibboleth_pw_expires=>undef
-shibboleth_pw_expires=>time()
Defines the UNIX time, after which a Shibboleth User should be forced to change his shibboleth_pw by the login script that handels Shibboleth password checks.

-vip_id=>undef
-vip_id=>$user_id
undef or '' means the user does not validate with VIP (but with nethz or shibboleth). A legal vip_id is an email address or a username consisting of 2 to 255 letters and digits from the standard ASCII character set.

-vip_pw=>undef
-vip_pw=>$plaintext_password
When -vip_id is undef or '', -vip_pw must be undef or '' as well. Otherwise a plain text password is expected. It must be at least 2 characters long. It is crypted and any later reference to it will return it crypted. There is no way to get it back in plain text.

$user->delete;
Deletes the object, both in memory and on the VIP database.

Grant Roles to a User

$user->set_roles($set_ids, $of_ids);
There are two arguments, each is a reference to an array of role_ids. First, all roles in $of_ids are revoked, then the roles in $set_ids are granted. You may read it as 'set roles set_ids of of_ids'.

Not every admin session may be allowed to grant/revoke all roles. Roles have an attribute granters_property; only sessions with this property are allowed to grant/revoke that role to a registred VIP user. Roles with an empty granters_property should not be granted/revoked manually at all; they are granted automatically depending on validation attributes to sessions - not users - in the login process.

The method set_roles does not check this rules. They should be implemented in the scripts which call the set_roles method. set_roles checks, that no role is granted (included in <@$set_ids>) that is not in the set of allowed roles (included in <@$of_ids>).

Manipulate Teacher Group membership of an User

$user->set_teacher_group( -set=>$teacher_group_id );
$user->set_teacher_group( -set=>\@teacher_group_ids );
$user->set_teacher_group( -delete=>$teacher_group_id );
$user->set_teacher_group( -delete=>\@teacher_group_ids );
$user->set_teacher_group( -delete=>'all' );
Sets and deletes teacher group memberships of a user. If set and delete are combined in one call, deletes are processed first. If a membership should be defined more than once, it is defined only once, without rising an error.

Search Dialog

Users->select_dialog( ... )
Class method used by CGI scripts to let the surfer search and select a user. This method displays a page with a form to enter query arguments and displays the results of searches. The result list contains a link to the matching users. The links URLs point to the same script with a querystring ?selected_user=Ident.

A CGI script using this method to make a search user dialog, should interpret the following two CGI params:

$cgi->param('selected_user'): if defined, this parameter contains the id of the user that was searched for and then selected by the surfer.

$cgi->param('cancel'): if defined, the surfer wants to cancel the search. he should be redirected to some other place.

Arguments:

-cgi=>$cgi
Required. Handle to a CGIsession object.

-vipstyle=>$style
Required. Handle ta a VipStyle object.

-title=>iso_8859_1_string
Optional. Passed to method page_header() of the VipStyle object: HTML title.

-status=>html_string
Optional. Passed to method page_header() of the VipStyle object: may be displayed in the status field.

-head=>html_string
Required. Title in content part of page.

-single_selection=\&coderef
Optional. The &coderef subroutine will be called, if only one user matches the search. The subroutine is called with one argument: the Ident of the user.

If -single_selection is not specified, there will be always a list of matching users displlayed in response to to a search by the surfer.

-search_role=>roles_id
Only users with explicitly granted role with ident roles_id will be selected.

Example:

    use strict;
    use vars qw($cgi $style);
    use CGIsession;
    use VipStyle;
    use Users;
    $cgi = CGIsession->connect();
    $style = VipStyle->new( -cgi=>$cgi );
    &handle_request unless $cgi->request_is_redirected();
    $cgi->save_session;
    sub handle_request {
        if ($cgi->param('selected_user')) {
            &do_something_with($cgi->param('selected_user'));
        } elsif ($cgi->param('cancel')) {
            print $cgi->redirect('...'); # the surfer canceled the search
        } else {
            $style->navigation( -highlight=>'example' );
            Users->select_dialog( -cgi=>$cgi,
                                  -vipstyle=>$style,
                                  -title=>'Browser Window Title',
                                  -head=>'Search a Good User',
                                  -single_selection=>\&do_something_with,
                                );
        }
    }
    sub do_something_with {
        my $user_id = shift;
        my $user = Users->find( -id=>$user_id );
        ...
    }


SEE ALSO

The class Login.pm grants roles (see Roles.pm) to sessions when a surfer validates himself. Roles give properties (see Properties.pm) to sessions.

Access to VIP database goes through VipDB.pm.

The select_dialog is based on CGIsession.pm for session tracking and CGI interface; the HTML page layout is based on VipStyle.pm.


COPYRIGHT

Copyright 2004-2013 Thedi gerber@id.ethz.ch