NAME

Maypole::Plugin::Authentication::UserSessionCookie - Track sessions and, optionally, users

SYNOPSIS

use Maypole::Application qw(Authentication::UserSessionCookie);

sub authenticate {
    my ($self, $r) = @_;
    $r->get_user;
    return OK if $r->user;
    return OK if $r->table eq "user" and $r->action eq "subscribe";
    # Force them to the login page.
    $r->template("login");
    return OK;
}

DESCRIPTION

This module allows Maypole applications to have the concept of a user, and to track that user using cookies and sessions.

It provides a number of methods to be inherited by a Maypole class. The first is get_user, which tries to populate the user slot of the Maypole request object.

get_user

$r->get_user;

get_user does this first by checking for a session cookie from the user's browser, and if one is not found, calling check_credentials, whose behaviour will be described momentarily. If a session cookie is found, the userid (uid) is extracted and passing to uid_to_user which is expected to return a value (typically a User object from the model class representing the users of your system) to be stored in the user slot. The session hash is also placed in the session slot of the Maypole request for passing around user-specific session data.

login_user

This method is useful for the situation in which you've just created a user from scratch, and want them to be logged in. You should pass in the user ID of the user you want to log in.

check_credentials

The check_credentials method is expected to be overriden, but the default implementation does what most people expect: it checks for the two form parameters (typically user and password but configurable) and does a search on the user class for those values. See "Configuration" for how the user class is determined. This method works well if the model class is Class::DBI-based and may not work so well otherwise.

check_credentials is expected to return two values: the first will be placed in the uid slot of the session, the second is the user object to be placed in $r->user.

If the credentials are wrong, then $r->template_args->{login_error} is set to an error string.

uid_to_user

By default, this returns the result of a retrieve on the UID from the user class. Again, see "Configuration".

logout

This method removes a user's session from the store and issues him a cookie which expires the old cookie.

Session tracking without user authentication

For some application you may be interested in tracking sessions without forcing users to log in. The way to do this would be to override check_credentials to always return a new ID and an entry into some shared storage, and uid_to_user to look the user up in that shared storage.

Configuration

The class provides sensible defaults for all that it does, but you can change its operation through Maypole configuration parameters.

First, the session data. This is retrieved as follows. The Maypole configuration parameter $config->auth->{session_class} is used as a class to tie the session hash, and this defaults to Apache::Session::File. The parameters to the tie are the session ID and the value of the $config->auth->{session_args} configuration parameter. This defaults to:

{ Directory => "/tmp/sessions", LockDirectory => "/tmp/sessionlock" }

You need to create these directories with appropriate permissions if you want to use these defaults.

For instance, you might instead want to say:

$r->config->auth({
    session_class => "Apache::Session::Flex",
    session_args  => {
        Store     => 'DB_File',
        Lock      => 'Null',
        Generate  => 'MD5',
        Serialize => 'Storable'
     }
});

The cookie name is retrieved from $config->auth->{cookie_name} but defaults to "sessionid". It defaults to expiry at the end of the session, and this can be set in $config->auth->{cookie_expiry}.

The user class is determined by $config->auth->{user_class} in the configuration, but defaults to a 'User' subclass of your base class (e.g. BeerDB::User). This typically corresponds to a 'user' table in the database.

The field in the user class which holds the username is stored in $config->auth->{user_field}, defaulting to user; similarly, the $config->auth->{password_field} defaults to password.

AUTHOR

Simon Cozens, simon@cpan.org Maintained by Marcus Ramberg, marcus@thefeed.no

This may be distributed and modified under the same terms as Maypole itself.

SEE ALSO

Maypole