/ 
Schema-RDBMS-AUS-0.04
River stage one • 1 direct dependent • 1 total dependent
/ Schema::RDBMS::AUS

NAME

Schema::RDBMS::AUS - Authentication, Users and Sessions in an SQL schema

SYNOPSIS

$ migrate-database-schema --dsn DBI:Pg: --verbose Schema::RDBMS::AUS

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.

The Schema::RDBMS::AUS distribution provides a complete transactional, mid-level interface to users, groups, and sessions, including:

  • SQL schema defining users, sessions, groups, permissions, and a security log

  • A rich user object and user management script

  • A CGI::Session subclass (CGI::Session::AUS) for session management

  • Sessions are serialized in a MySQL or PostgreSQL database, using YAML, a data serailization language that is easily read both by humans and most popular programming languages.

This package only supplies an API for the management of users and sessions, it does not integrate them with any particular user interface.

If you are developing a web application that needs authentication, users, and sessions, see Apache2::AUS. Apache2::AUS provides a mod_perl2 handler over top of Schema::RDBMS::AUS that manages users and sessions, which can then be used by other mod_perl2 modules, CGI scripts, or even PHP/Ruby/Python.

INSTALLING THE DATABASE SCHEMA

Currently, PostgreSQL (7.4 and above) and MySQL (5.0 and above) are supported.

To install the database schema, use the migrate-database-schema utility, supplied by the DBIx::Migration::Directories distribution. For example, the following line would install the schema into the MySQL database 'joe':

$ migrate-database-schema --dsn DBI:mysql:database=joe --verbose Schema::RDBMS::AUS

NOTE: For both the PostgreSQL and MySQL schemas, it's best to install them as the database superuser.

PostgreSQL

The entire PostgreSQL database schema can be installed by a regular database user so long as the plpgsql language is already installed in the database you wish to use. If plpgsql is not installed, Schema::RDBMS::AUS will attempt to install it for you. This requires database administrator privileges.

MySQL

With MySQL, you're really better off just installing the entire schema as root. The permissions system for CREATE VIEW and CREATE TRIGGER in MySQL are a bit screwed up, and if your user doesn't have permissions to install these objects, the situation is even worse: MySQL auto-commits a transaction after each CREATE TABLE, meaning that a half-finished, failed schema installation can not be backed out properly.

I've tried all sorts of crazy GRANT statements and have not yet successfully installed this schema as an unprivileged user and have concluded that MySQL is pretty much braindead.

Once the schema is installed, it can be accessed with a regular user with no problems.

MANAGING SESSIONS

See CGI::Session::AUS.

MANAGING USERS, GROUPS, AND PERMISSIONS

See Schema::RDBMS::AUS::User.

ENVIRONMENT

The following environment variables are used by Schema::RDBMS::AUS:

AUS_DB_DSN
AUS_DB_USER
AUS_DB_PASS

The DBI Data Source Name, Username, and Password to connect to the database with. If any of these environment variables are not specified, the DBI standard DBI_DSN, DBI_USER, and DBI_PASS variables are checked as well.

AUS_SESSION_ID

If this environment variable is specified, it is used as the default session id for CGI::Session::AUS.

METHODS

Most of the methods you would be interested in are probably in Schema::RDBMS::AUS::User or CGI::Session::AUS. However, Schema::RDBMS::AUS itself provides a few class methods:

dbh

Returns a DBIx::Transaction database handle connected to the authentication, users, and sessions database. It accepts the same arguments as connect() in the DBI distribution. If any parameters are not specified, their default values are taken from the environment as described above.

sdbh

Obtains a database handle from dbh(), then asks DBIx::Migration::Directories if our SQL schema is installed there. If it is, the database handle is returned. If not, sdbh will die() with a useful error message.

THANKS

Mischa Sandberg <mischa.sandberg@telus.net>

Mischa has taught me quite a bit about Postgres in general, and wrote the triggers and views that are used to support hierarchical user/group membership.

Mark Stosberg <mark@summersault.com>

Mark maintains CGI::Session, the package that made CGI::Session::AUS possible. He also provided some constructive criticism in his review of Schema::RDBMS::AUS (http://cpanratings.perl.org/dist/Schema-RDBMS-AUS), and let me into the CGI::Session subversion tree so that I could implement the YAML and JSON CGI::Session serializers.

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.