NAME

Ucam::WebAuth::CGIAA - CGI interface to the University of Cambridge Web Authentication Service.


SYNOPSIS

    use Ucam::WebAuth::CGIAA;
    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;
    ...


DESCRIPTION

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:

    Ucam::WebAuth::CGIAA->new;

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.


DEPENDENCIES

This module relies on the following perl modules (which may have their own dependencies):

Ucam::WebAuth::Ticket (at least version 0.05)
CGI::Cookie
Time::Local
URI::Escape
Carp


METHODS

$aa = Ucam::webAuth::CGIAA->new( %parameters )

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:

auth_service
The full URL for the web login service to be used. Defaults to https://raven.cam.ac.uk/auth/authenticate.html

description
A text description of the resource that is requesting authentication. This may be displayed to the user by the authentication service. It is restricted to printable ASCII characters (0x20 - 0x7e) though it may contain HTML entities representing other characters. The characters '<' and '>' will be converted into HTML entities before being sent to the browser and so this text can not usefully contain HTML markup.

hostname
The 'official' hostname of the webserver running the CGI. The agent needs to know this reliabably so that it can recognise authentication responses intended for it and reject attempts to replay authentication responses intended for other servers. Unfortunatly the CGI provides no reliable way for a script to obtain this information - the SERVER_NAME environment variable is normally derived directly from the 'Host:' header in the corresponding HTTP request and is therefore under the control of a potential attacker. This parameter MUST be set.

response_timeout
Responses from the central authentication server are time-stamped. This parameter sets the period of time in seconds during which these responses are considered valid. The default is 30 seconds.

clock_skew
Interpretation of response_timeout is difficult if the clocks on the server running the CGI and on the authentication server are out of step. Both servers should use NTP to synchronize their clocks, but if they don't then this parameter should be set to an estimate of the maximum expected difference between them (in seconds).

key_dir
The name of a directory containing the public key(s) required to validate authentication responses sent by the server. Default /etc/httpd/conf/webauth_keys

do_session
If true (the default) the agent will create and maintain a cookie containing information obtained from the authentication service so that accesses other than the first will not require redirection to the authentication server. Once the cookie is established and while it remains valid, authentication will complete without any redirection each time the CGI program is invoked.

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.

max_session_life
The maximum period of time (in seconds) for which an established session will be valid. This may be overriden if the authentication reply contains a shorter 'life' parameter. Note that this does NOT define an expiry time for the session cookie - session cookies are always set without an expiry time, causing them to expire when the browser session finishes. Default is 2 hours.

timeout_message
A re-authentication by the authentication service will be triggered when an established session expires. This option sets a text string, default 'your login to the site has expired', which is sent to the authentication server to explain to the user why they are being asked to authenticate again. HTML markup is suppressed as for description above.

cookie_key
A random key used to protect session cookies from tampering. Any reasonably unpredictable string (for example an md5sum of a rapidly changing logfile) will be satisfactory. This key must be the same for all uses of the Web Authentication system that will receive the same session cookies (see cookie_name, cookie_path, cookie_domain below). If sessions are being managed (see do_session) then setting this parameter is required.

cookie_name
The name used for the session cookie. When used for access to resources over https the string '-S' is appended to this name. The default is 'Ucam-WebAuth-Session'.

cookie_path
The 'Path' attribute for the session_cookie. The default is the 'directory' component of the path to the script currently being executed. This should result in the cookie being returned to future requests for this script and for other resources in the same 'directory' - see the important note about cookie_key above.

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!!

cookie_domain
The 'Domain' attribute for the session cookie. The default is 'undef' which will cause the 'Domain' attribute to be omitted when seting the cookie. This should result in the cookie being returned only to the server running the script. Be aware that some people may treat with suspicion cookies with domain attributes that are wider than the host setting the cookie.

debug
If set to a true value, additional trace and debugging information may be created by calls to warn().

($complete,$headers) = $aa->authenticate( %options )

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.

aauth
Sets the aauth parameter in any authentication request sent to the authentication server. This sets the types of authentication that would be acceptable - see the 'wls2waa protocol' for details. Since only one type is currently supported (password) it's not of much use. Any script that sets this parameter must subsequently check that the type of authentication actually used matches - see auth and sso.

interact
Sets the iact parameter in any authentication request sent to the authentication server - see the 'wls2waa protocol' for details. Possible values are 'yes' and 'no'. Any script that sets this parameter must subsequently check that the type of authentication actually used matches - see auth and sso.

parameters
Sets the params parameter in any authentication request sent to the authentication server - see the 'wls2waa protocol' for details. The content of this parameter will be returned in a subsequent authentication_response and can be accessed via $aa->params.

fail
If true, sets the fail parameter in any authentication request sent to the authentication server to 'yes'. This has the effect of requiring the authentication server itself to report any errors that it encounters, rather than returning an error indication. Note however that even with this parameter set errors may be detected by this module that will result in authentication failing here.

$aa->status

Returns the three digit status code indicating the result of the authentication attempt. Only valid when the $complete flag returned by $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 values are

$aa->success

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.

$aa->msg

Returns a text description corresponding to the status code returned by $aa->status. Only valid when the $complete flag returned by $aa->authenticate is true.

$aa->issue

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. 19850412T232050Z.

$aa->expire

The time/date that this authentication will expire. This will calculated from $aa->issue and the lower of max_session_life or the remaining session lifetime returned from the authentication service. This date/time is in the same format as $aa->issue above.

$aa->id

The identifier of the authentication assertion on which the users authentication is based.

$aa->principal

Indicates the authenticated identity of the browser user. Only valid if $aa->status == 200.

$aa->auth

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

$aa->sso

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

$aa->params

Returns the value of the parameters attribute of the corresponding authenticate call.

Get/set methods for authentication object attributes

The following methods set (if called with an argument) and return the values of the identically-named attributes of the authentication object.

$aa->auth_service
$aa->description
$aa>do_session
$aa->response_timeout
$aa->key_dir
$aa>cookie_key
$aa->cookie_name
$aa->cookie_path
$aa->cookie_domain
$aa>cookie_timeout
$aa>timeout_message
$aa->debug


SUPPRESSING SESSION MANAGEMENT

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.


BUGS

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.


AUTHOR

Jon Warbrick (jon.warbrick@ucs.cam.ac.uk)


COPYRIGHT

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.


SEE ALSO

perl(1), 'The Cambridge Web Authentication System: WAA->WLS communication protocol'.