password results from the CPAN

Apache-SessionManager

=head3 NOTES ON USING F<.htaccess> INSTEAD OF F<httpd.conf>

=over 4

=item *

In both cases it is necessary to install
L<Apache::SessionManager|Apache::SessionManager> in C<Header parsing>  phase
and not into C<URI translation> phase (in this phase, F<.htaccess> hasn't yet 
been processed).

=item *

Using F<.htaccess>, it is possible to use only cookies for the session
tracking.

=back

=head2 THE AUTHENTICATION HANDLER

This simple code is the authentication handler
F</usr/local/apache/perl/Apache/MyAyth.pm>:

   package Apache::MyAuth;
   use Apache::Constants qw(:common REDIRECT);
   use Apache::SessionManager;
   use strict;

   sub handler {
      my $r = shift;
      my $session = Apache::SessionManager::get_session($r);

      # Login ok: user is already logged or login form is requested
      if ( $session->{'logged'} == 1 || $r->uri eq $r->dir_config('MyAuthLogin') ) { 
         return OK;
      }

      # user not logged in or session expired

      # store in session the destination url if not set
      $session->{'redirect'} ||= $r->uri . ( ( $r->args ) ? ('?' . $r->args) : '' );

      # verify credenitals
      unless ( verifiy_cred( ($r->args) ) ) {

         # Log error
         $r->log_error('MyAuth: access to ' . $r->uri . ' failed for ' . $r->get_remote_host);

         # Redirect to login page
         $r->custom_response(FORBIDDEN, $r->dir_config('MyAuthLogin'));
         return FORBIDDEN;
      }
      $session->{'logged'} = 1;

      # Redirect to original protected resource
      $r->content_type('text/html'); 
      $r->header_out( Location => $session->{'redirect'} );
      return REDIRECT;     
   }

   # Check correct username and password with your own policies
   sub verifiy_cred {
      my %cred = @_;
      return 1 if ( $cred{'username'} eq 'foo' && $cred{'password'} eq 'baz' );
      return 0;
   }

   1;

Now we write an essential login form code
F</usr/local/apache/htdocs/protected/login.html> (save it according to
C<PerlSetVar MyAuthLogin> setting):

   <HTML>
   <BODY>
   <FORM METHOD="GET">
      <INPUT TYPE="test" NAME="username" SIZE="10">
      <INPUT TYPE="password" NAME="password" SIZE="10">
      <INPUT TYPE="submit" VALUE="Login">
   </FORM>
   </BODY>
   </HTML> 

=head3 NOTE ON CUSTOM ERROR MESSAGE WITH MSIE

The recently released version of Microsoft's Internet Explorer (from 5.x) has
some new "features" (?) which may affect sites.

The first new "feature" is that MSIE 5 may replace a site's own error messages
with its in-built error pages. This occurs if the error page from the site is
less than a particular size.

For most errors, this is 512 bytes. If the error page from the site is more
than 512 bytes, MSIE 5 will display the site's error message, otherwise it will
not display it.

For a few statuses (403, 405 and 410), the cut-off size is 256. The solution to
this problem is to ensure that all error pages are greater than 512 bytes.

However note that most of Apache's built in error messages will be less than
512 bytes, so the only way to ensure that viewers see the site's real error 
pages is to use the ErrorDocument directive in Apache.

So, because we redefine C<FORBIDDEN> response (status 403) with the HTML form,
in order to work with MSIE, we must ensure to put more than 512 bytes into 
I<login.html> file! 

=head2 TESTING Apache::SessionManager

Now, you you can test authentication mechanism by accessing some resources
under protected area.
In our case launch: http://localhost/protected/foo.html.

Note that the authorization can be applied also on dinamic contents (for
example mod_perl handlers, CGI, etc) simply by setting right content handler
in protected C<Location>s.

=head1 USING Apache::SessionManager WITHOUT SYSTEM ADMINISTRATOR ACCOUNT

=head2 INTRODUCTION

This section illustrates how to use module without any system administrator
account (usually C<root>) in a machine.

Generally, this means that you cannot:

=over 4

=item * 

install modules in standard directories

=item * 

configure F<httpd.conf> Apache

=back

SessionManager/cookpod.pod view on Meta::CPAN

ports (for example > 1024) the only possibilty to use session manager is to
configure F<.htaccess> file appropriately.

Using F<.htaccess>, you must install
L<Apache::SessionManager|Apache::SessionManager> in C<Header parsing> phase of
Apache request instead of C<URI translation> phase. Moreover, it is possible to
use only cookies for the session tracking.

This is an example of how configure F<.htaccess> file for use session (using
file system as backend datastore) with CGI scripts under 
L<Apache::Registry|Apache::Registry>:

   <IfModule mod_perl.c>
      <Perl>
         use lib '/path/to/your/perl-lib/lib/site_perl',
                 '/path/to/your/perl-lib/lib/';           # for Storable.pm
      </Perl>
      PerlModule Apache::SessionManager
      <FilesMatch "\.cgi$">
         SetHandler perl-script
         PerlHandler Apache::Registry
         PerlSendHeader On
         PerlSetupEnv On
         Options ExecCGI
         PerlHeaderParserHandler Apache::SessionManager

         PerlSetVar SessionManagerTracking On
         PerlSetVar SessionManagerExpire 300
         PerlSetVar SessionManagerInactivity 1800
         PerlSetVar SessionManagerName SESSIONID
         PerlSetVar SessionManagerStore File
         PerlSetVar SessionManagerStoreArgs "Directory => /path/to/session/data"
         PerlSetVar SessionManagerDebug 5
      </FilesMatch>
   </IfModule>   

To test session you can use this simple CGI script:

   #!/usr/bin/perl

   use Data::Dumper ();

   my $session = Apache::SessionManager::get_session(Apache->request);
   $session->{$$ . '-' . rand()} = rand; 

   print "Content-type: text/html\n\n";
   print '<PRE>' . Data::Dumper::Dumper($session) . '</PRE>'; 

Save it with a F<.cgi> extension (like F<session.cgi>) in the same directory
where you have F<.htaccess> and make it executable by web server.

=head1 USING Apache::SessionManager AND Apache::DBI 

=head2 INTRODUCTION

This section describes how to use
L<Apache::SessionManager|Apache::SessionManager> with
L<Apache::DBI|Apache::DBI> when using a RDBMS for sessions back-end datastore.

L<Apache::DBI|Apache::DBI> is a useful mod_perl module that caches database
connections according to args (like DBD driver, user, password) and attributes.
So, if your application uses a different user and/or attributes to connect to a
(different) database, every connection will be cached. Also, every child could
have these cached DB's handles. L<Apache::DBI|Apache::DBI> works very well for
web applications that uses same DB user.

=head2 CONFIGURATION

There is no need of extra configuration steps to use advantage of persistent DB
connections offered by L<Apache::DBI|Apache::DBI> when using
L<Apache::SessionManager|Apache::SessionManager> with a RDBMS as session
datastore.

L<Apache::DBI|Apache::DBI> overrides DBI C<connect> and C<disconnect>  methods
and it intercepts, transparently, all related calls (including
L<Apache::SessionManager|Apache::SessionManager> DBI calls) by returning cached
connections, if any. 

Simply add a line like:

   PerlModule Apache::DBI

in your F<httpd.conf>, or:

   use Apache::DBI;

in a F<startup.pl> file where you can also setup your initial persistent
connection.

However, remember that you must load L<Apache::DBI|Apache::DBI> module before
L<DBI|DBI> or any module that uses it! 

=head2 TESTING

Restart the server and... test your application :-)

Additionally, you can enable perl-status console by putting, before loading
L<Apache::DBI|Apache::DBI>, lines like:

   <Location /perl-status>
      SetHandler perl-script
      PerlHandler Apache::Status
      # or PerlResponseHandler Apache::Status in mod_perl 2
   </Location>   

You will see in the 'DBI connections' page, the cached datasource (in current
child) used by Apache::Session::* plugin datastore you've chosen.  Also yo can
start C<httpd> in single mode with C<-X> option to work with a single child.

=head2 SEE ALSO

L<Apache::DBI|Apache::DBI>

=head1 MOVING SESSION EXPIRATION POLICIES TO THE CLIENT SIDE

=head2 INTRODUCTION

This section describes how to move expiration policies on the client side by
setting expiration cookie properties appropriately.

=head2 CONFIGURATION

( run in 0.891 second using v1.01-cache-2.11-cpan-39bf76dae61 )