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:

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

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

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

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

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

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

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

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

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

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).

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.


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


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.


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.

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

Include only users who are members of a teacher group.

Include only users who are members of teacher group 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:
ISO-8859-1 string. 2 to 255 characters long.

ISO-8859-1 string. 2 to 255 characters long.

Sets the last action time to the current time.

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'.

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.

undef or '' means the user does not valiadte through nethz.

undef or '' may mean one of two things: the users npid is not known or he is not registred in nethz.

undef or '' means the user does not validate with shibboleth.

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.

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.

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.

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.

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.


Required. Handle to a CGIsession object.

Required. Handle ta a VipStyle object.

Optional. Passed to method page_header() of the VipStyle object: HTML title.

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

Required. Title in content part of page.

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.

Only users with explicitly granted role with ident roles_id will be selected.


    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();
    sub handle_request {
        if ($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,
                                  -title=>'Browser Window Title',
                                  -head=>'Search a Good User',
    sub do_something_with {
        my $user_id = shift;
        my $user = Users->find( -id=>$user_id );


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 2004-2013 Thedi gerber@id.ethz.ch