ABSTRACT

This class encapsulates roles of VIP applications.

Roles have a set of properties, which are used as switches in the application. What a session can do depends on the properties in effect.

Some properties are calculated by the application. But most of them are set at login time based on the roles which are granted to the user.

Roles have the following attributes:

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

Name
The name is a nonempty, unique ISO-8859-1 string of 2 to 30 character length.

Description
Role objects have a description, which is a nonempty ISO-8859-1 string of 2 to 255 characters length.

Granters Property
Any role can be granted to users at login time depending on validation attributes. If a user validates with Shibboleth, the shibboleth attributes will be tested (see below). If a user validates against the nethz data base, his Ngroup memberships can be checked. This tests use information provided by the validation system (shibboleth or nethz); the users may or may not be permanently registred in the VIP database.

The Granters_Property is either undef or a property name. Only roles with a defined Granters_Property can be granted explicitly to registred VIP users; this are typically roles for highly privileged, handpicked admins. The session which explicitly grantes the role to a registred VIP user, should itself have the property specified with the attribute Granters_Property.

Nethz_test
Shibboleth_test
This are the tests to be performed for nethz or shibboleth validated users: They are Perl expressions which will be evaluated. If they evaluate to true, the role is granted to the logging in user, otherwise not.

For nethz validation, the validation attributes are the Ngroups to which the user belongs. They are in a hash %attr. The keys are the ngroup names, the values are any true value. Ngroup names are for example Leitzahlen for employees.

Example: Check if the user is in ngroup 'T0070' but not in '00072':

 $attr{'T0070'} && ! $attr{'00072'}

For shibboleth, the validation attributes are in a hash %attr with the keys and values as given by shibboleth.

Example: Check if the users swissEduPersonHomeOrganization is 'unibe.ch'

 $attr{swissEduPersonHomeOrganization} eq 'unibe.ch'


SYNOPSIS

 use Roles;
 $role = Roles->find(-name=>'Role name');
 $string = $role->description();
 $string = $role->name();
 $role->update(-name=>$new_name, -description=>$new_string);


DESCRIPTION

Object Constructor

$role = Roles->find( -id=>Ident );
$role = Roles->find( -name=>Name );
Object constructor. Roles are identified by an Ident, which is unique and will never change. They also have a Name, which may be any ISO-8859-1 string, is unique but can be changed. If the desired role is not found, an empty object is returned is returned. CGI programs may use the class method Roles->select_dialog( ... ) to let the surfer select a role.

$role = Roles->create( );
Creates an object in memory but not on the VIP database. Its content should be set with the $role->update()-method, which will update the VIP database as well if the input checks pass. The first update should set at least the -name, -description and -granters_property attributes.

$aref = Roles->get_object_list( -all=>1 );
$aref = Roles->get_object_list( -including_property=>property_name );
$aref = Roles->get_object_list( -granted_by_property=>property_name );
$aref = Roles->get_object_list( -granted_to=>users_id );
Returns a reference to a list of role objects. Called with argument -all=>1, the list contains all roles. Called with argument -including_property=>property_name, the list contains only roles which have the property property_name assigned. Called with argument -granted_by_property=>property_name, the list contains only roles which can be granted by sessions with property property_name. Called with argument -granted_to=>users_id, the list contains only roles which are granted to the registred user users_id.

$aref = Roles->get_id_list( ... );
Returns a reference to a list of role idents, not blessed objects. Same arguments as Roles->get_object_list( ... );.

Object Accessor Methods

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

$string = $role->description;
$string = $role->id;
$string = $role->name;
$string = $role->granters_property;
$string = $role->nethz_test;
$string = $role->shibboleth_test;

Object Modifier Method

($field, $errmsg) = $role->update( ... )
Updates the role (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:
-name=>$string
ISO-8859-1 string. 2 to 30 characters long. Must be unique.

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

-nethz_test=>undef
-nethz_test=>$perl_expression
undef or '' will not automatically grant the role to users validating against the nethz system. Otherwise it should be a legal validation attribute check. See Nethz_test above.

-shibboleth_test=>$perl_expression
undef or '' will not automatically grant the role to users validating through the shibboleth system. Otherwise it should be a legal validation attribute check. See Shibboleth_test above.

$aref = Roles->granters( );
$href = Roles->granter_labels( );
This two class methods are provided for CGIs who define or edit role definitions. A role can be granted to other users only by admins who have a Granters Property. This methods return information to build a popup menu to specify a granters property for a role.

Roles->granters() returns a reference to an array of property names, one of which may be required for admins to grant a role; Roles->granter_labels() returns a reference to hash with labels to the property names.

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

Assign Properties to Roles

$role->set_properties( $property_name_array_ref );
Deassigns all properties of the role object and assigns the properties in $property_name_array_ref to the role. $property_name_array_ref must be a reference to an array of property names.

Search Dialog

Roles->select_dialog( ... )
Class method used by CGI scripts to let the surfer search and select a role. 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 roles. The links URLs point to the same script with a querystring ?selected_role=Ident.

Arguments:

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

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

-no_search=>1
Optional. There will be no search form, but just the list of all roles.

-search_property=>property_name
Optional. Restricts the selectable roles to roles which have property property_name assigned.

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

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

-head=>$html_string
Required. Title in content part of page. Passed to method page_header() of the 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.

Example:

    use strict;
    use vars qw($cgi $style);
    use CGIsession;
    use VipStyle;
    use Roles;
    $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_role')) {
            &do_something_with($cgi->param('selected_role'));
        } else {
            Roles->select_dialog( -cgi=>$cgi,
                                  -vipstyle=>$style,
                                  -title=>'Browser Window Title',
                                  -head=>'Search a Good Role',
                                  -single_selection=>\&do_something_with,
                                );
        }
    }
    sub do_something_with {
        my $role_id = shift;
        my $role = Roles->find( -id=>$role_id );
        ...
    }


SEE ALSO

Roles are granted to users with method set_roles in Users.pm.

Properties are described in Properties.pm.

Class Login.pm grants roles to sessions when a surfer validates himself.

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