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:

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:

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:

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;

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;

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.

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.