view release on metacpan or  search on metacpan

Session/Session.pm  view on Meta::CPAN

####################################################################
#
# CGI::Session
#
# A module which makes LDAP authentication and session state
# much easier to manage.
#
####################################################################
#
# Generalized by Jeff Younker
# jyounker@inktomi.com (or jeff@math.uh.edu)
#
# Many thanks for the basic code and idea go to Luke
# Sheneman (sheneman@inktomi.com).
#
####################################################################

package CGI::Session;
use strict;

use vars qw($VERSION);
$VERSION = '0.9c';

use CGI::Carp;
use CGI;
use Date::Format;
use DBI;

=head1 NAME 

  CGI::Session - CGI cookie authentication against an LDAP database

=head1 ABSTRACT

  Provides a simple API authenticate users against an LDAP server, and then
  to cache this authentication information between invokations of CGI scripts
  without sending passwords subsequent to login.

  The state information is maintained in a combination of a cookie, a database,
  and a magic passkey which is sent in the contents of the web page.  Acquiring
  the login thus requires stealing both the cookie and a current copy of the
  web page.

  CGI::Session also contains a subclass of CGI which transparently injects
  the passkey into forms.  It is strongly suggested that you use this class.

=head1 SYNOPSIS

=head2 Setting Things Up

use CGI::Session;
use CGI;

  my $cgi = new CGI::Session::CGI;
  my $session = new CGI::Session( $cgi );
  $cgi->session( $session );

  my $session_store = new CGI::Session::CookieJar::DBI;
  $session_store->set( -cookie_name=>'cookie_name',
                       -username=>'myuser',
                       -password=>'kjsdfdf',
                       -host=>'dbhost',
                       -database=>'mydb',
                       -cookie_table=>'cookiejar' );
  $session->set( -cookie_jar => $session_store );


  $session->auth_servers(
	[ new CGI::Session::LDAPServer(
	    'ldap.server.my.domain',                  # host
            389,                                      # port
            'ou=my,ou=domain',                        # root
	    'ou=people,ou=my,ou=domain'               # base
	    'uid=$username,ou=people,ou=my,ou=domain' # bind
	) ] );

   $session->open;

=head2 Performing the Initial Login

   my $action = $cgi->param('action');
   my $passkey = $cgi->param('passkey');

   if ( defined $action and $action eq 'Log In' )
     {
       my $username = $cgi->param('username');
       my $password = $cgi->param('password');
       if ( $session->authenticated( $username, $password ) )
	 {
	   $session->set_passkey( $user );
	   $session->set_login_cookie( $user );

	   # Notice that we use $session->header and not $cgi->header
	   #
	   print $session->header();
	   print $cgi->start_html( 'Login Succeeded' );
	   ...

	   # The passkey is sent via the cgi wrapper.
	   #
	   my $passkey = $session->passkey;
	   print $cgi->start_form( -action=>'http://my.stupid/script.cgi' );

	   print ...your form here...

Session/Session.pm  view on Meta::CPAN

    }
  else
    {
      Authentication Failed
    }

=cut

sub authenticate
  {
    my ( $self, $username, $password ) = @_;
    if ( $self->authenticated( $username, $password ) )
      {
	$self->set_passkey( $username );
	$self->set_login_cookie( $username );
      }
  }

# Authorization happens at two points, so I've separated it out.
# Returns true if the user is accepted, false if they are not.
#
# $is_authorized = $session->authorize( $auth_token );
#
=item CGI::Session::authorize

An internal function which performs authorization.  It must be called _after_ authentication has happened.  Used as follows:

my $auth_token = { -username=>$user, -group=>$group };
my $authorized = $session->authorize( $auth_token );

=cut

sub authorize
  {
    my ( $self, $auth_token ) = @_;
    my $authorization_servers = $self->authorization_servers;

    # We succeed if there are no authorization servers.
    #
    return 1 unless $authorization_servers;

    # Make a single authorization server look the same as many.
    #
    if ( ref($authorization_servers) ne 'ARRAY' )
      {
	$authorization_servers = [ $authorization_servers ];
      }

    # Check each one of the authorization servers in turn.  If any one
    # of them succeeds then the user is accepted.
    #
    foreach my $server ( @{$self->authorization_servers} )
      {
        return 1 if $server->authorized( $auth_token );
      }
    return 0;
}

##############################################################
#
# Wrapper for CGI.pm's header function which transparently
# handles creation of the cookie.
#

sub header_args_with_cookie
  {
    my ($self,%raw_args) = @_;

    # Copy the arguments.  If we find a cookie argument
    # then we add in any cookies that we already know about.
    #
    my @processed_args ;
    my $cookie_is_done = 0;
    foreach my $arg (keys %raw_args)
      {
	push @processed_args, $arg;
	my $val = $raw_args{$arg};
	if ($arg=~/^-?cookie$/i and $self->cookie )
	  {
	    if ( ref($val) eq 'ARRAY' )
	      {
		push @{$val}, $self->cookie;
	      }
	    else
	      {
		$val = [ $val, $self->cookie ]
	      }
	    $cookie_is_done = 1;
	  }
	push @processed_args, $val;
      }

    # If no cookies were found in the argument list then
    # we create one.
    #
    if ( $self->cookie and !$cookie_is_done )
      {
	push @processed_args, '-cookie';
	push @processed_args, $self->cookie;
      }

    return @processed_args;
  }


=item CGI::Session::header

Acts just like CGI.pm's header function, but it injects
the authentication cookie.

If you are using CGI::Session::CGI then this function will not be
used.  If you are using CGI.pm directly then call this function instead
of CGI.pm's header method.

  print $session->header;
  print $cgi->start_html( 'my html' );
  ...

=back

=cut