NAME
SYNOPSIS
DESCRIPTION
METHODS
BEFORE YOU START
AUTHOR INFORMATION
SEE ALSO
BUGS
COPYRIGHT

NAME

KuPortal - Interface to KU's KuPortal Authentication Service

SYNOPSIS

  use CGI;
  use KuPortal;
  
  # Set the common application URL prefix.
  my $app = 'www.ku.edu/cgiwrap/myacct/myappdir';
  my $mydept = '1234000';
  
  # Log the user out if they click "Logout" button.
  if (param('Logout')) {
    KuPortal::logout(-application => $app,
                     -message     => "Logged out of my page");
  }
  
  # Log the user in if they click "Login" button.
  if (param('Login')) {
    KuPortal::login(-application => $app,
                    -message     => "Please log into my page");
  }
  
  # Retrieve the user's information, forcing a login if they're not
  # already logged in.
  my $user_info =
    KuPortal::user_status(-application => $app,
                          -timeout     => 5 * 60, # Five minutes
                          -message     => "Please log into my page",
                          -asref       => 1);
  
  # If user is not in our department, they can't use the page.
  if ($user_info->get_value('deptno') ne $mydept) {
    print_not_authorized_page();
  }
  
  # Print the attribute values in a table.
  print "<table border=1>\n";
  foreach my $attr ($user_info->attributes) {
    print "<tr><td>$attr</td><td>";
    # Print multiple values separated by a line break.
    print join('<br>', $user_info->get_value($attr));
    print "</td></tr>\n";
  }
  print "</table>\n";

DESCRIPTION

KuPortal checks against a list of authorized web applications to see if the user has logged in, and if so, returns identification information for the user. If not, it redirects the user to the login page, which prompts for the user's Online ID, which is generally their Exchange username and password (it's actually their directory.ku.edu LDAP login, but they're generally equivalent). If the user enters correct information, it redirects back to the original page, allowing the page to retrieve the desired user information.

KuPortal requires that the web applications using it be run as a secure pages, that is, the URL must begin with https:// and that all embedded links begin with https:// as well, and that the web server have a valid SSL certificate installed.

The application web page program should adhere fairly closely to the order of calls in the SYNOPSIS, above. In particular, since the KuPortal::login and KuPortal::logout methods do not return to the calling Perl program, the program must never call them unconditionally. Otherwise, you will never actually get past those calls in the application program.

If your application does not allow anonymous access, you can skip the test for a "Login" button, above.

The timeout value controls how often the user's session is verified against the portal session. Using a value of 0 (zero) verifies the session each time the application page is loaded and causes the user information not to be cached locally. This will slow down the loading of the page considerably.

METHODS

KuPortal::user_status ( OPTIONS )

Checks to see if the user is logged into the web page with a valid session. If so, it returns the user's identification information, otherwise it redirects the browser to the login page.

The KuPortal authentication service customizes the information for each web page that uses the service. See the BEFORE YOU START section below.

The following options are supported.

-application => $app_str: Specifies the application that this web page belongs to. This will be an initial substring of the URL, but without the https:// included. This option is required.
-timeout => $seconds: Specifies how many seconds can elapse before the application's session must be verified against the portal session. Setting this to small values gives higher assurance that the same user is still logged in. Setting it to 0 (zero) verifies the session each time the application web page is loaded, and doesn't cache the user's information locally. The default is 0 (zero).
-message => $message_str: An optional message to print on the login query page, letting the user know what application is requesting login.
-parameters => $get_arg_str: An optional string containing URL encoded CGI arguments in GET format to pass to the application when it is logged in.
-asref => 1: An optional argument which, if set, causes a KuPortal::Entry object to be returned instead of a list containing a text string. KuPortal::Entry objects have methods to retrieve the user attributes by name. But, the portal session attributes must have been set up with this in mind.
-dont_force_login => 1: An optional flag. If it is true, the application is not redirected to the login page if it is not logged in. Instead, an empty list is returned. The default is false.

If -asref is true, KuPortal::user_status returns a KuPortal::Entry object, containing the user's attributes, plus the -idle_time, -verify_time, and -session_time attributes.

Otherwise, it returns a list containing the $user_info, $idle_time, $verify_time, and $session_time values. The $user_info value is a text string which the calling program must parse.

idle_time: The number of seconds from the previous call to KuPortal::user_status.
verify_time: The number of seconds from the most recent session verification.
session_time: The number of seconds from the most recent login for this browser session.

The time values returned can normally be ignored, but an application could use them to enforce re-authentication sooner than the portal would normally require it.

Example

 $user_info =
   KuPortal::user_status(-application => $application,
                         -timeout     => $timeout,
                         -asref       => 1,
                        );

KuPortal::login ( OPTIONS )

Forces an authentication request. It does not return, because it redirects the user's browser to the KuPortal login page.

This method can be used for forcing the user to re-authenticate after a certain amount of time, or to allow the user to log in as a different user ("If you are not so and so, click here").

The following options are supported.

-application => $app_str: Specifies the application that this web page belongs to. This will be an initial substring of the URL, but without the https:// included. This option is required.
-message => $message_str: An optional message to print on the login query page, letting the user know what application is requesting a login.
-return_url => $url_str: A text string specifying the web page to log into. If -return_url is not supplied, the current page's URL is assumed. You should only specify this parameter if this page is an introductory page, allowing the user to log into a different application page, or if you wish to pass CGI GET parameters to your page. At this time, it is not possible to pass POST parameters through an KuPortal login.

KuPortal::logout ( OPTIONS )

Logs the user out by deleting the user information from the API query cache and by redirecting the user to the specified page, deleting the login cookie. It then prints a logout message, allowing the user to log back into the main portal.

-application => $app_str: Specifies the application that this web page belongs to. This will be an initial substring of the URL, but without the https:// included. This option is required.
-message => $message_str: An optional message to print on the login query page, letting the user know what application logged out.
-return_url => $url_str: A text string specifying the web page to redirect to after logout. If -return_url is not supplied, the default logout page is displayed. You should only specify this parameter if you have a specific reason to direct the user to a different location upon logout than the default logout page.

BEFORE YOU START

You must contact the KuPortal administrator at argus@ku.edu and specify a URL or the start of a URL to identify your page or pages. For instance, you could use

    https://www.ku.edu/cgiwrap/myuser/mydir

as your URL. If mydir is a sub-directory of cgi-bin on the myuser account, then any page in that directory (or its sub-directories) can use the service. If a user logs into one page, they will be considered to have logged into all pages that begin with the above URL. This URL is called an application, since the pages that begin with it use the same login information, and it is the text passed as the -application option to the methods above, NOT the URL of the current page.

You must also specify the information you wish returned to identify the users. There are too many options available to specify here, but one example would be to allow anyone with an Online ID to log in and the user information could be their name and either student ID or employee ID.

See http://argus.cc.ku.edu/auth for the current LDAP attribute list. Note that you will need to obtain permission from each attributes stakeholders in order to receive that attribute.

AUTHOR INFORMATION

The KuPortal system was developed by Kathryn Huxtable <khuxtable@ku.edu> for Academic Computing at the University of Kansas.

Address bug reports and comments to: argus@ku.edu

BUGS

At present, no bugs have been reported for this module. Please report bugs and comments to argus@ku.edu

COPYRIGHT

This library is not free software.

$Id: KuPortal.html,v 1.1 2005/11/15 23:21:28 huxtable Exp $