NAME

CGI::AIS::Session - Perl extension to manage CGI user sessions with external identity authentication via AIS

SYNOPSIS

  use DirDB;    # or any other concurrent-access-safe
                # persistent hash abstraction

  use CGI::AIS::Session;

  eval {
     my $Session = Authenticate(
             aissri <= 'http://www.pay2send.com/cgi/ais/',
             tieargs <= ['DirDB', './data/Sessions'],
             XML <= ['name','age','region','gender'],
             agent <= 'Bollow', # this is the password for the AIS service, if needed
             # nodie <= 1,  # suppress exception-throwing (support version 0.01 behavior)
             ( $$ % 100 ? () : (timeout <= 4 * 3600)) # four hours
     );
  };

  if ($@){
        my ($iden, $err) = $@ =~ /AIS: (.*) identity (.*) error/;

        if($iden eq 'NULL'){
           print "Location: http://www.pay2send.com/cgi/ais/login\n\n"
           exit;
        }elsif($iden eq 'ERROR'){
           print "Content-type: text/plain\n\n";
           print "There was an error with the authentication layer",
                 " of this web service: $err\n\n",
                 "please contact $ENV{SERVER_ADMIN} to report this.";
           exit;
        
        }else {
           die "Unexpected exception thrown by Authenticate: $@";
        };
  };

  tie my %UserData, 'DirDB', "./data/$$Session{identity}";
 

DESCRIPTION

This module creates and maintains a read-only session abstraction based on data in a central AIS server.

The session data provided by AIS is read-only. A second database keyed on the identity provided by AIS should be used to store persistent local information such as shopping cart contents. This may be repaired in future releases, so the session object will be more similar to the session objects used with the Apache::Session modules, but for now, all the data in the object returned by Authenticate comes from the central AIS server.

On the first use, the user is redirected to the AIS server according to the AIS protocol. Then the identity, if any, is cached under a session key in the session database as tied to by the 'tieargs' parameter.

This module will create a http cookie named AIS_Session.

Authenticate will croak on aissri methods other than http in this version.

Additional expected XML fields can be listed in an XML parameter.

If a 'timeout' paramter is provided, Sessions older than the timeout get deleted from the tied sessions hash.

'ERROR' and 'NULL' identities are not cached. In fact, they're not even returned. ERROR or NULL responses from the AIS server will cause the Authenticate module to die, which is usually what you want: A good AIS server will keep the user until they authenticate themselves instead of immediately serving a NULL response.

You can suppress the dieing by specifying a true value for the "nodie" parameter. This makes the module compatible with any software written around version 1.

Internally, the possible states of this system are:

no cookie because we're not accessing the server using the SERVER_NAME no cookie, no OTU OTU cookie

The second two return a session object. The first two cause redirection.

if a query string of AIS_LOGOUT is postpended to any url in the domain protected by this module, the session will be deleted before it times out.

ABOUT AIS

Authenticated Identity Service is a scheme for sharing single sign-on identity (and possibly other information) with participating services on distributed equipment. A compliant AIS server has three defined methods, "present" which maps a user identity to a one-time-use ticket, "query" which exchanges a block of AISXML for the corresponding ticket, and "about" which provides a human-readable description of the policies of the particular AIS server, such as how to log on, how to get an account, what additional data is provided by it, what the privacy policy is, how to become an affiliated to it and use its authentication realm, and if it is "hard" or "soft" and whether there is a corresponding AIS server of the other flavor.

"hard" AIS will offer the user a log-in screen when they access the "present" method without being logged in already. "soft" ais merrily sets up an OTU ticket for the NULL user and serves it.

EXPORTS

the Authenticate routine is exported.

AUTHOR

David Nicol, davidnico@cpan.org

SEE ALSO

http://www.pay2send.com/ais/ais.html

The Apache::Session family of modules on CPAN