NAME

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

SYNOPSIS

  use base qw(Apache::MVC Maypole::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 "{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 "{auth}{session_args}" configuration parameter. This defaults to:

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

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 "{auth}{cookie_name}" but defaults to "sessionid". It defaults to expiry at the end of the session, and this can be set in "{auth}{cookie_expiry}".

The user class is determined by "{auth}{user_class}" in the configuration, but attempts to guess the right user class for your application otherwise. Probably best not to depend on that working.

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

AUTHOR

Simon Cozens, "simon@cpan.org"

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