PUT results from the CPAN

Apache-SessionManager
=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

There are several situations like this:
( run in 1.233 second using v1.01-cache-2.11-cpan-437f7b0c052 )