Ucam::WebAuth::CGIAA - CGI interface to the University of Cambridge Web Authentication Service.
my $aa = Ucam::WebAuth::CGIAA->new(cookie_key => 'eb78ba43926c7b0222f28498', hostname => 'www.example.com');
exit unless $aa->authenticate;
die $aa->msg unless $aa->success;
my $issue = $aa->issue; my $expire = $aa->expire; my $id = $aa->id; my $principal = $aa->principal; my $auth = $aa->auth; my $sso = $aa->sso; my $params = $aa->params;
The University of Cambridge Web Authentication Service provides centralized, password-based user authentication for web-based access without disclosing users' passwords to individual sites. This system replies on the ability of HTTP responses to redirect a browser between an originally requested resource and the central authentication server, and uses a signed assertion from the authentication service to carry authentication information.
This module provides a 'application agent' object which interacts with the authentication service that can be called from a Perl CGI program.
To use the module, first create an authentication agent object by calling:
Authentication is initiated with the
authenticate object method.
Since the authentication process may require one or more HTTP
redirects before completion, the call to
authenticate returns an
'authentication complete' flag - unless authentication is complete the
CGI program should quit without sending any more data. The program
will be called again later in the authentication sequence and will
eventually get a chance to proceed beyond the authentication
step. Note that CGI programs protected by this module may be invoked
several times before they get the chance to actually operate and
return data to the user.
Whether or no authentication is complete, the module may print one or
more CGI headers. For this reason,
authenticate must be called
while headers are still being added and before the blank line
signaling the end of headers is printed.
Once authentication has completed, the CGI can query the authentication agent object to discover if authentication was successful, the identity of the person authenticating, etc.
The agent will normally maintain a session cookie to cache the user's authentication information (since repeated round trips to the authentication service will be slow and are discouraged). This can be suppressed, for example for applications that maintain their own session data which could conveniently include authentication information.
This module relies on the following perl modules (which may have their own dependencies):
This class method constructs a new application agent object.
Key/value pair arguments can be used to initialize the agent's parameters; alternatively, identically-named instance methods can be used to set (if called with an argument) or query the parameter settings. Most parameters have default values that are suitable for general use and so initializing most parameters is optional. The exception is that hostname must be set and cookie_key must be set if do_session is true.
The parameters are:
key(s)required to validate authentication responses sent by the server. Default /etc/httpd/conf/webauth_keys
Automatic use of a session cookie can be suppressed, for example for applications that maintain their own session data which could conveniently include authentication information, but there are drawbacks to doing so - see Suppressing Session Management.
See http://wp.netscape.com/newsref/std/cookie_spec.html and RFC 2109 for various vague and self-contradictory statements about how a cookie's 'Path' attribute is intended to work. Note that seting cookie_path to undef will result in a path of '\' being used becasue Internet Explorer is rumored to object to cookies with no path. Note also that Lynx appears to object to cookies with paths that end with the script's name itself. Argh!!
This method actually triggers an authentication exchange. The call returns a list of two scalar values: an 'authentication complete' flag and possibly a set of CGI headers. If there are any headers then the calling CGI program must return them to the webserver, normally by printing them to STDOUT. Unless the complete flag is set then the CGI should quit without sending any further data to the webserver.
Because CGI headers may need to be output following a call to
authenticate, this call must come before the CGI generates its
normal headers, and in particular before the first blank line
printed by the CGI program (since this terminates the headers) and
before the CGI prints a 'Status' header.
Key/value pairs can be used to set parameters for this authentication attempt. All are optional.
Returns the three digit status code indicating the result of the
authentication attempt. Only valid when the
$complete flag returned
$aa->authenticate is true. Values below 600 are as for the
status field in an authentication_response as defined in the wls2waa
protocol. Values in the range 600-699 are used by this module. Possible
Returns true if an authentication request was successful. This a
shorthand for checking that
$aa->status == 200. Only valid when the
$complete flag returned by
$aa->authenticate is true.
Returns a text description corresponding to the status code returned
$aa->status. Only valid when the
$complete flag returned by
$aa->authenticate is true.
The time/date that the authentication assertion on which the users
authentication is based was issued by the authentication service. This
date/time is in the format specified by RFC 3339 except that
time-offset is always 'Z', there are no fractional seconds, and the
punctuation is ommited, e.g.
The time/date that this authentication will expire. This will
$aa->issue and the lower of
or the remaining session lifetime returned from the authentication
service. This date/time is in the same format as
The identifier of the authentication assertion on which the users authentication is based.
Indicates the authenticated identity of the browser user. Only valid
$aa->status == 200.
This indicates which authentication type was used if authentication was established by interaction with the user. This value consists of a single text token. The only value currently in use is 'pwd'.
This indicates which authentication types were previously used if authentication was established based on previous successful authentication interactions with the user. This value consists of a a sequence of text tokens separated by ','. The only value currently in use is 'pwd'.
Returns the value of the parameters attribute of the corresponding authenticate call.
The following methods set (if called with an argument) and return the values of the identically-named attributes of the authentication object.
The agent will normally maintain a session cookie to cache the user's authentication information (since repeated round trips to the authentication service will be slow and are discouraged). This can be suppressed by setting the object's do_session parameter to 0. Doing so might be apropriate for applications that maintain their own session data which could conveniently include authentication information.
However there are drawbacks to doing so. The agent trys to ensure that, once authentication is complete, the URL in the browser's 'Location' bar is the URL the user originally requested. It does this by issuing an additional redirect back to the URL originally requested and storing details from the authentication response (including success/failure, error messages, etc) in the session cookie. Without a cookie it can't do this, with the result that the URL the user is left with will be the authentication response - typically the user's original URL with additional information in a CGI parameter called 'WLS-Response'. Applications that chose to suppress automatic session management should make their own arrangements to 'clean up' the URL.
If redirects are required in response to a POST request (for example as a result of a form submission) the the resulting redirection via the login server will result in the loss of any POST data submitted with the request. This is likely to annoy users, since it is most likely to occur (as a result of session timeout) when a long, difficult to complete form is submitted. It may be possible to address this shortcoming in a future version of this module.
Jon Warbrick (firstname.lastname@example.org)
Copyright (c) 2004,2005 University of Cambridge. You can redistribute it and/or modify it under the terms of the GNU Lesser General Public License.
perl(1), 'The Cambridge Web Authentication System: WAA->WLS communication protocol'.