/ 
Apache2-AUS-0.02
River stage zero No dependents
/ Apache2::AUS

NAME

Apache2::AUS - Authorization, Users, and Sessions for Apache2.

SYNOPSIS

In httpd.conf:

PerlModule            Apache2::AUS
PerlInitHandler       Apache2::AUS->Init

Then in a mod_perl handler:

my $session = $r->aus_session;
if($session->param('foo')) {
    ...
}

DESCRIPTION

Note: This is an alpha release. The interface is somewhat stable and well-tested, but other changes may come as I work in implementing this on my website.

Apache2::AUS is a mod_perl package that provides access to Schema::RDBMS::AUS sessions and users from Apache2. For a more detailed description of Authentication, Users, and Sessions with Schema::RDBMS::AUS, see it's documentation. Environment variables and some other required settings are documented there.

This document focuses on how to use the apache2 bindings to access (or restrict access based upon) Schema::RDBMS::AUs's users, groups, and sessions:

ACCESS TO THE SESSION OBJECT

The AUS_SESSION_ID envrionment variable is set by the 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 CGI::Session::AUS object to manipulate it. Apache2::AUS will flush all of it's changes to the session object just before apache's 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. 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 CGI::Session::AUS and CGI::Session for more information about the session object.

HANDLERS

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

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

The 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" (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 "_Fixup" below.

This handler always returns OK.

Response

In Apache2::AUS, the Response handler is responsible for logging the user in. This handler will read any GET / POST arguments (via 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;

go

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

go_error

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

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

Authen

The 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:

valid-user

You must be logged in to view this page.

user-id

You must be logged in as one of the specified user ID's to view this page.

Example:

# only users 4, 10, and 20 may view this page.
require user-id 4 10 20
user-name

You must be logged in as one of the specified user names to view this page.

Example:

# bob, job, and nob can view this area.
require user-name bob job nob
flag

One of the specified flags must be set to view this page, either on the requesting user, or a group that user is a member of:

Examples:

# If you have either the "Cool" or "Neat" flags set, you can view this page
require flag cool neat

# You need both "dirty" and "smelly" flags to view this page.
require flag dirty
require flag smelly

EXAMPLES

See the "examples/" directory for httpd.conf examples, and samples on how to manipulate Apache2::AUS sessions from different environments and scripting languages.

TODO

  • Fix the kludginess of the login handler. It's the only thing that reads GET/POST arguments, but the whole go/go_error setup seems imperfect to me right now. If you come up with a better solution, patches are welcome. :)

  • Add examples for using Apache2::AUS from PHP and Ruby on Rails, and evolve the Apache2::AUS/Schema::RDBMS::AUS interfaces to make this easier.

  • Add many more unit tests.

  • Bring documentation up-to-date with API.

AUTHOR

Tyler "Crackerjack" MacDonald <japh@crackerjack.net>

LICENSE

Copyright 2006 Tyler "Crackerjack" MacDonald <japh@crackerjack.net>

This is free software; You may distribute it under the same terms as perl itself.

SEE ALSO

Schema::RDBMS::AUS, CGI::Session::AUS, http://perl.apache.org/.