view release on metacpan or  search on metacpan

lib/Apache2/AUS.pm  view on Meta::CPAN

=head1 ACCESS TO THE SESSION OBJECT

The C<AUS_SESSION_ID> envrionment variable is set by the
L<Schema::RDBMS::AUS|Schema::RDBMS::AUS> package for each request,
so you can look up the session data manually in the database if you
want, or initialize your own L<CGI::Session::AUS|CGI::Session::AUS>
object to manipulate it. Apache2::AUS will flush all of it's changes
to the session object just before apache's C<HTTP Response> phase,
so you should always have the most current information and be able
to save your changes safely. Here's an example of how to obtain the
session from a CGI script:

  #!perl

  use strict;
  use warnings;
  use CGI;
  use CGI::Session::AUS;
  
  my $cgi = CGI->new;
  
  my $session = CGI::Session::AUS->new
      or die "I need a session object to continue!";
  
  if($session->param("has_cheese")) {
    print $cgi->header, "You have cheese!\n";
    exit;
  }

When operating under mod_perl, it's usually more efficient to pick up
the existing session object yourself. L<Apache2::AUS|Apache2::AUS> makes
this convienent for you by adding an "aus_session" method which you can
use in your own mod_perl handlers:

  sub handler {
    my $r = shift;
    my $session = $r->aus_session
        or die "I need a session to continue!";
        
    if($session->user) {
      ...
    }
  }

See L<CGI::Session::AUS|CGI::Session::AUS> and L<CGI::Session|CGI::Session>
for more information about the session object.

=head1 HANDLERS

All handlers should be called as "class methods" in your C<httpd.conf>, eg:

  <Location /login>
    PerlResponseHandler   Apache2::AUS->Response
  </Location>

=over

=item Init

The C<Init> handler ensures that a session has been attached to this
HTTP request. If the client specified a session ID, that session is loaded
into Apache's request record. Otherwise, a new one is created. This handler
also sends the session cookie back to the user's web browser, and sets
"$r->user" (C<REMOTE_USER> environment variable)

This handler should be applied to every request where having a session
may be useful. Eg;

  <VirtualHost www.myhost.com>
    DocumentRoot /home/myhost/htdocs
    PerlInitHandler     Apache2::AUS->Init
  </VirtualHost>

This handler will also install another handler into to
ensure that your session is saved at the end of each request. See
L</_Fixup> below.

This handler always returns OK.

=item Response

In Apache2::AUS, the C<Response> handler is responsible for logging the user
in. This handler will read any GET / POST arguments (via
L<Apache2::Request|Apache2::Request> so other handlers can use them later).
If "user" and "password" are supplied, a login will be attempted under that
user id. If "logout" is supplied, any logged-in user will be logged out.

If the login was unsuccessful, the AUS_AUTH_FAILURE environment
variable will be set to a string containing the reason why.

This handler always returns OK, and will do an internal redirect to a page
based on the "go" and "go_error" GET / POST arguments;

=over

=item go

The user will be redirected here if the login was successful, or a logout
was requested.

=item go_error

The user will be redirected here if the login was unsuccessful, or if no
login or logout was requested.

=back

Keep in mind these are B<internal> redirects. Apache rewrites environment
variables when doing an internal redirect, so to check for the reason a
login failed, you should check the C<REDIRECT_AUS_AUTH_FAILURE> environment
variable.

=item Authen

The C<Authen> handler is responsible for determining if the current user
is allowed to access a page. The authorization requirements are specified
using apache's standard "require" directive.

The following "require"ments are recognized: