verify results from the CPAN

Apache-SessionManager

and this is a F<session.tt2> TT2 template (it's the same than the
L<Apache::Template|Apache::Template> version!)

   [% USE my_sess = Apache.SessionManager %]
   <HTML>
   <HEAD>
   <TITLE>[% title %]</TITLE>
   <BODY>

   The session dump
   [% USE dumper %]
   <PRE>
   [% dumper.dump(my_sess.session) %]
   </PRE>

   <H3>Getting session values</H3>
   Sigle session value<BR>
   ID is [% my_sess.get('_session_id') %]<P>

   Multiple session values<BR>
   [% FOREACH s = my_sess.get('_session_id','_session_timestamp') %]
   * [% s %]<BR>
   [% END %]<P>

   Multiple values by array ref<BR>
   [% keys = [ '_session_id', '_session_start' ];
      FOREACH s = my_sess.get(keys) %]
   * [% s %]<BR>
   [% END %]

   All session values<BR>
   [% FOREACH s = my_sess.get %]
   * [% s %]<BR>
   [% END %]

   <H3>Setting session values:</H3>
   ID: [% my_sess.set('foo' => 10, 'bar' => 20, '_session_test' => 'test') %]<BR>

   </BODY>
   </HTML>  

Save both into the F</usr/local/apache/perl-scripts> directory and launch
http://localhost/perl/session.cgi

=head2 SEE ALSO

L<Apache::SessionManager|Apache::SessionManager>, L<Template Toolkit|Template>,
L<Apache|Apache>, perl(1)

=head1 Apache::SessionManager WITH AUTHENTICATION MECHANISM

=head2 INTRODUCTION

This section describes using L<Apache::SessionManager|Apache::SessionManager>
with simple authentication mechanism.  There are many ways to do it; this
document will not describe all possible configurations. 

=head2 CONFIGURATION

The idea is to write a custom authentication handler in order to verify each
request  that session is valid (the user has been already authenticaded).

=head3 CONFIGURATION VIA F<httpd.conf>

In F<httpd.conf> (or any files included by the C<Include> directive):

   PerlModule Apache::SessionManager
   PerlTransHandler Apache::SessionManager
   <Location /protected>

      PerlSetVar SessionManagerTracking On
      PerlSetVar SessionManagerExpire 3600
      PerlSetVar SessionManagerInactivity 1800
      PerlSetVar SessionManagerName SESSIONID
      PerlSetVar SessionManagerStore File
      PerlSetVar SessionManagerStoreArgs "Directory => /tmp/apache_session_data/"

      <Perl>
         use lib '/usr/local/apache/perl/';
      </Perl>
      PerlAuthenHandler Apache::MyAuth
      AuthName "Reserved Club"
      AuthType Basic
      require valid-user
      PerlSetVar MyAuthLogin /protected/login.html
   </Location>

We have added a C<PerlSetvar> directive in order to set C<MyAuthLogin> variable
with login form URI.

=head3 CONFIGURATION VIA F<.htaccess>

In the case you don't have access to F<httpd.conf>, you can put similar
directive  directly into an F<.htaccess> file:

   PerlModule Apache::SessionManager
   <FilesMatch "\.foo$">

      PerlHeaderParserHandler Apache::SessionManager
      PerlSetVar SessionManagerTracking On
      PerlSetVar SessionManagerExpire 3600
      PerlSetVar SessionManagerInactivity 1800
      PerlSetVar SessionManagerName SESSIONID
      PerlSetVar SessionManagerStore File
      PerlSetVar SessionManagerStoreArgs "Directory => /tmp/apache_session_data/"

      <Perl>
         use lib '/usr/local/apache/perl/';
      </Perl>
      PerlAuthenHandler Apache::MyAuth
      AuthName "Reserved Club"
      AuthType Basic
      require valid-user
      PerlSetVar MyAuthLogin /protected/login.html
   </FilesMatch>

The only difference is that you cannot use C<Location> directive (I used
C<FilesMatch>) and you must install
L<Apache::SessionManager|Apache::SessionManager> in C<Header parsing> phase of
Apache request instead of C<URI translation> phase.

=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.
( run in 0.489 second using v1.01-cache-2.11-cpan-e1769b4cff6 )