ABSTARCT

This class is used by login scripts to set up session data of the VIP application. It contains only two public class methods; there are no objects of this class.

There are currently three login scripts:

login_vip.cgi
Validates against the VIP database

login_nethz.cgi
Validates against the nethz database and gets information from the nethz system as attributes.

login_shibboleth.cgi
Uses shibboleth to validate the surfer and gets the attribute from his home organisation.

This scripts use Login->setup_login_data to setup the session. They pass it the collected attributes which will be translated to the internal norm of the VIP session.


SYNOPSIS

  #!/usr/bin/perl -w
  use strict;
  use vars qw($cgi $style);
  use CGIsession;
  use VipStyle;
  use Login;
  use Users;
  $cgi = CGIsession->connect();
  $style = VipStyle->new( -cgi=>$cgi );
  &handle_request() unless $cgi->request_is_redirected( needs_validation=>0 );
  $cgi->save_session;
  sub handle_request {
      if ($cgi->param('login')) {
          # check username and password
          # setup %attributes from external validation system
          $cgi->lock_session_after(...);      # define timeout in seconds
          $cgi->recheck_password_dialog(...); # define script to recheck pw after timeout
          my $user = Login->setup_login_data( ... );
          if ($style->error_msg) {
              &save_validation_data();
              &print_registration_form();
          } else {
              $cgi->session_is_validated( -validated_as=>$user->id, ... );
          }
      } elsif ($cgi->param('register')) {
          &restore_validation_data();
          my $user = Login->setup_login_data( ... );
          if ($style->error_msg) {
              &print_registration_form();
          } else {
              $cgi->session_is_validated( -validated_as=>user->id, ... );
          }
      } else {
          &print_login_form();
      }
  }
 sub print_login_form { ... }        # form to enter username/password
 sub print_registration_form { ... } # form to enter/correct validation data
 sub restore_validation_data { ... } # saved to $cgi->private_data
 sub save_validation_data { ... }    # save to $cgi->private_data


DESCRIPTION

$user = Login->setup_login_data( ... );
Sets up the session for the specified user. If the user does not exist as a registred VIP user, he will be registred. If he is already registred, his registration data may be updated. In both cases, there may be errors reported from class Users method update. If such an error occures, it is reported using the VipStyle methods error_msg and focus.

When registration passes, properties are set to the session depending on the roles granted to the logged in user. Information about the logged in user, his roles and attributes are kept in session_data. This informations can be retrieved later as described below.

Returns the Users object.

Arguments:

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

-vipstyle=>$style
Required. Handle to the VipStyle object.

-username=>$iso_8859_1_string
Required. 2 to 255 characters long.

-firstname=>$iso_8859_1_string
Optional. 2 to 255 characters long. If absent or empty, the firstname will be kept from an already registred user; in case of a not yet registred user, a missing firstname will result in an error.

-lastname=>$iso_8859_1_string
Optional as described under firstname.

-email=>$rfc_822_string
Optional but see firstname. RFC 822 format ie. theodor.gerber@id.ethz.ch

-user=>$user_object
Optional. Handle to the Users object, if the user was already looked up on the VIP database for validation checking.

-validation_by=>'vip'
-validation_by=>'nethz'
-validation_by=>'shibboleth'
Required. Validation system.

-attributes=>\%attributes
User attributes as reported by the validation system. For nethz, this will be a hash with ngroup names as keys and irrelevant values, which will be true. For shibboleth the keys will be the LDAP attribut names as described in shibboleth with the values as given by shibboleth.

Method setup_login_data sets up VIP internal data in session storage for validated users. This includes:

Login Attributes

The login type is saved in session storage and can be retieved by calling $cgi->session_data('LOGIN_validation_by') This will return 'vip', 'nethz', or 'shibboleth'.

The passed login attributes are saved and can be retrieved later from session storage with $cgi->sesssion_data('LOGIN_ATTR_attribute_name'); The validation attribut names and values are depending on the validation system.

$cgi->session_data('LOGIN_msg') is a HTML string that may be used by VipStyle page_header to be displayed in the status field. It contains the name and login time of the surfer.

$cgi->session_data('LOGIN_name') is a ISO-8859-1 string consisting of firstname and lastname of the surfer.

$cgi->session_data('LOGIN_email') is a computer readable email addresss in the RFC 822 format ie. gerber@id.ethz.ch

$cgi->session_data('LOGIN_username') is the identification of the validation system. For shibboleth ist is the swissEduPersonUniqueID, for nethz the nethz-username and for locally registred users the username used to login.

$cgi->session_data('LOGIN_roles') is a HTML string of role names which where granted to the user at login time.

Properties

The method setup_login_data evaluates which roles should be granted to the logging in user and sets the appropriate properties in session storage. They are named 'PROPERTY_' followed by the name of the property. i.e.

  if ($cgi->session_data('PROPERTY_is_vegetarian')) {
      # this code is for surfers with the property 'is_vegetarian' only.
  }

Roles may be granted explicitly to registred users and/or on the fly depending on validation attributes of a logging in user. This is defined with each role; method setup_login_data applies the rules to evaluate, which roles should be granted to the user.

Properties may be set by roles and/or calculated based on dependence of other properties. Both kinds are set by method setup_login_data.

There is a third way to set a property: based on granted access to resources. This third kind of properties is set in other parts of the application.


SEE ALSO

The CGI scripts login_nethz.cgi and login_vip.cgi are examples of usage.


COPYRIGHT

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