NAME

Authen::Ticket::Server - Perl extension for implementing ticket authentication.

DESCRIPTION

Authen::Ticket::Server is an abstract class which provides the skeleton upon which a full ticket issuing master authentication server may be built. With appropriate subroutine definitions, the resulting class may provided authentication for either trusted or untrusted client sites.

The class may be used to implement a ticket server either as a mod_perl handler (see Authen::Ticket) or as a CGI script (using the object methods).

If the server class is a sub-class of Authen::Ticket::Signature (or comparable class), the ticket will automatically be signed.

SERVER OBJECT

Authen::Ticket::Server provides an object encapsulating most of the information required to authenticate a user and generate tickets. The following values are contained in the object:

    $server = new Authen::Ticket::Server;
    $$server{_r}     -> Apache request object iff running under mod_perl
    $$server{stdout} -> object to print to for HTML pages
    $$server{query}  -> CGI-like object for generating HTML and accessing
                        form data
    $$server{request_uri}
    $$server{TicketDomain}  -> domain for which ticket is valid
    $$server{TicketExpires} -> default ticket lifetime

The class constructor will work with sub-classes without modification. Sub-class initialization should be placed in the initialize subroutine.

SUB-CLASSING

A sub-class is required to override any of the methods mentioned in this documentation (e.g., authentication method, HTML forms). Two variables are required in the sub-class package.

@ISA

This array determines the classes the sub-class will inherit from. For a fully functioning server, this must include Authen::Ticket::Server. If the tickets are to be signed, Authen::Ticket::Signature is recommended.

%DEFAULTS

This hash contains the default values (or undef) for the configuration options required by the sub-class. These are set in the httpd configuration with the PerlSetVar directive. These are available in the $self hash reference.

Example

  package My::Ticket::Server;
  @ISA = (qw/Authen::Ticket::Server Authen::Ticket::Signature/);
  %DEFAULTS = (
    TicketUserDatabase => 'mysql:users',
    TicketDatabaseUser => undef,
    TicketDatabasePassword => undef,
    TicketUserFields   => 'table:userfield:passwordfield',
  );

GENERAL METHODS

The following methods need not be redefined in any sub-classes.

$server = new Authen::Ticket::Server([$r], [%options]): This will return an initialized server object. If $r is a reference and the code is running under mod_perl, then $$server{_r} will be set to $r. Otherwise, all the arguments are taken to belong to a hash defining the default configuration.
This method is used in Authen::Ticket->handler and is useful in CGI scripts implementing a ticket server. However, the preferred use of the Authen::Ticket modules is in a mod_perl environment.

SUB-CLASS FUNCTIONS

The following conventions are used in these sections:

  $server -> server object
  $u      -> hashref of user authentication information
  $t      -> hashref of ticket information
  $s      -> additional information for inclusion in a message

SUB-CLASS REQUIRED FUNCTIONS

Any sub-class of Authen::Ticket::Server must define the following subroutines:

$t = $server->authenticate($u)

This subroutine returns a hashref of information to be placed in the ticket if the user is authenticated. If the person is not authenticated, it should return undef.

The following values are added to $t by $server->handler after authenticated returns successfully:

  fields -> comma separated list of fields in %$t
  uid    -> $u->{user}
  ip     -> browser IP information depending on $u->{security}
  expiry -> expiration time of the ticket

The default implementation will place a warning in the log file (if running under mod_perl) and refuse authentication.

SUB-CLASS RECOMMENDED FUNCTIONS

Any sub-class of Authen::Ticket::Server should define the following subroutines:

$q = $server->get_query_object

This subroutine returns an object used to retrieve form values and format HTML. This must be CGI or another class that implements the CGI interface (e.g., a sub-class of CGI).

The default implementation will return a valid CGI object of type $CGI::DefaultClass.

This routine is used in the object constructor to initialize part of the object.

$o = $server->get_stdout_object

This subroutine returns an object to be used as STDOUT. This must support the $o->print() syntax.

The default implementation will return the object to which STDOUT is tied (usually Apache->request object).

This routine is used in the object constructor to initialize part of the object.

$u = $server->get_userinfo

This subroutine returns a hash reference to the information on the authenticating person. Some massaging of the data may take place. This routine transfers data from the input form to an internal representation for further processing.

The following fields are expected for correct authentication:

  user     -> username
  password -> password
  duration -> lifetime of the ticket
  security -> {weak,medium,strong} extent to which the browser IP is used

The default implementation will pull the above values from the query object.

$c = $server->construct_cookie(%$t)

This subroutine returns an intermediate value for the ticket. This routine may combine the values in %$t in any manner deemed necessary as long as the client website can deconstruct them.

$c = $server->encode_cookie($c)

This subroutine encodes the cookie. This may involve encryption or other transforms. However, Authen::Ticket::Signature provides the code for signing tickets.

The default implementation base_64 encodes the cookie.

SUB-CLASS MISCELLANEOUS FUNCTIONS

Any sub-class of Authen::Ticket::Server may define the following subroutines:

$server->no_cookie_error_message($s): This subroutine returns an HTML page to be sent to the browser when the ticket server has detected a lack of support for cookies.
$server->no_user_password_error_message($s): This subroutine returns an HTML page to be sent to the browser when the server needs the authentication information from the user. The optional $s parameter will contain any error messages from the previous authentication attempt if there was one. $uri is the URI of the page the server will return to when the user has successfully authenticated.
$server->go_to_uri_message: This subroutine returns an HTML page to be sent to the browser when the user has successfully authenticated. This page does not need to redirect the browser to $uri. $uri is provided to help those browsers that cannot redirect themselves automatically.

AUTHOR

James G. Smith <jgsmith@tamu.edu>

COPYRIGHT

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

 1. Redistributions of source code must retain the above copyright 
    notice, this list of conditions and the following disclaimer.
 2. Redistributions in binary form must reproduce the above 
    copyright notice, this list of conditions and the following 
    disclaimer in the documentation and/or other materials 
    provided with the distribution.
 3. Neither the name of the University nor the names of its 
    contributors may be used to endorse or promote products 
    derived from this software without specific prior written 
    permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTERS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 376:: '=item' outside of any '=over'
Around line 402:: You forgot a '=back' before '=head1'
Around line 419:: You forgot a '=back' before '=head1'
Around line 432:: '=item' outside of any '=over'
Around line 451:: You forgot a '=back' before '=head1'
Around line 455:: '=item' outside of any '=over'
Around line 510:: You forgot a '=back' before '=head1'
Around line 514:: '=item' outside of any '=over'
Around line 534:: You forgot a '=back' before '=head1'