NAME

DESCRIPTION

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

    $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

@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

$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

  $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

$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

$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

$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

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.

SEE ALSO

POD ERRORS

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'