Dave Rolsky > Catalyst-Plugin-AuthenCookie > Catalyst::Plugin::AuthenCookie

Download:
Catalyst-Plugin-AuthenCookie-0.07.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.07   Source  

NAME ^

Catalyst::Plugin::AuthenCookie - DEPRECATED - use CatalystX::AuthenCookie

SYNOPSIS ^

    use Catalyst qw( AuthenCookie );

    $c->set_authen_cookie( value => { user_id => 1234 } );

    my $value = $c->authen_cookie_value();

    print $value->{user_id};

    $c->unset_authen_cookie();

DESCRIPTION ^

This module is deprecated. Use CatalystX::AuthenCookie instead.

This plugin provides a few methods to help you implement a secure cookie-based implementation scheme. It does not interact with the Catalyst::Plugin::Authentication system, and expects that you will implement the actual logging in and out inside your controller code.

What it does provide is a few methods for setting a cookie and retrieving it later, along with some configuration of that cookie.

When it sets a cookie, it adds a MAC (Message Authentication Code) to the cookie. The MAC is based off of the cookie's values and a server-side secret you provide. This allows the plugin to verify that the cookie is valid when it receives it from the client on future requests, and prevents a malicious client from forging a user id. The cookie is still vulnerable to hijacking (as are most common web authentication mechanisms).

METHODS ^

This class provides the following methods:

$c->set_authen_cookie( value => $value, expires => $expires )

This method takes a value and an optional expires parameter and sets a cookie based on those values, as well as this plugin's configuration.

The value parameter must be a hash reference. Presumably, it will contain something like a user id, which will allow you to identify the user on future requests.

The expires parameter is optional. If given, it should be something that CGI::Cookie can handle, like "+1d".

Also see the CONFIG section for more details on configuring the cookie.

$c->unset_authen_cookie()

This method removes the cookie from the client by sending a new cookie header with an expiration time in the past and an empty value.

$c->authen_cookie_value()

This method returns a hash reference containing the value of the authentication cookie. This method simply returns false if there is no cookie or if the MAC is invalid.

CONFIG ^

The top-level configuration key for this plugin is "authen_cookie". Most of the configuration keys correspond to CGI::Cookie constructor parameters, and reading that module's documentation may be helpful. The follow config keys are available for this module:

USAGE EXAMPLE ^

This module does not provide a complete authentication solution, and will require some code on your side to tie things together.

Presumably, you want to be able to identify a user on each request and probably make a object from one of your model classes for that user. You also need to decide when to set and remove the cookie, presumably in your controller.

Here are some examples of each piece you might implement. First, a login action in your controller:

  package MyApp::Controller::User;

  sub login : Local
  {
      my $self = shift;
      my $c    = shift;

      my $email = $c->request()->param('email_address');
      my $pw    = $c->request()->param('password');

      my $user =
          MyApp::Model::User->new( email    => $email,
                                   password => $pw,
                                 );

      if ( ! $user )
      {
          # login failed, do something to handle that
      }

      my %expires;
      %expires = ( expires => '+1y' )
          if $c->request()->param('remember');

      $c->set_authen_cookie( value => { user_id => $user->user_id() },
                             %expires,
                           );

      # redirect to some other page
  }

One thing to note is that the user will not be retrievable from the cookie until the next request. If you always redirect after a form POST this isn't an issue, but for some apps it may be important.

The logout action is even simpler:

  package MyApp::Controller::User;

  sub logout : Local
  {
      my $self = shift;
      my $c    = shift;

      $c->unset_authen_cookie();

      # redirect
  }

Finally, we need a small plugin to retrieve the user from the cookie on request:

    package MyApp::Plugin::User;

    use strict;
    use warnings;

    use base 'Class::Accessor::Fast';

    __PACKAGE__->mk_accessors( '_user', '_checked_cookie' );


    sub user
    {
        my $self = shift;

        my $user = $self->_user();

        unless ( $user || $self->_checked_cookie() )
        {
            $user = $self->_get_user_from_cookie();
            $self->_user($user);
            $self->_checked_cookie(1);
        }

        return $user;
    }

    sub _get_user_from_cookie
    {
        my $self = shift;

        my $cookie = $self->authen_cookie_value();

        return unless $cookie && $cookie->{user_id};

        return MyApp::Model::User->new( user_id => $cookie->{user_id} );
    }

    1;

Loading this plugin gives you a $c->user() method which fetches the user on demand. The _checked_cookie attribute is there to prevent us from checking for the cookie repeatedly when the cookie does not exist or reference a valid user. Another solution would be to return an object representing a guest user as a default.

AUTHOR ^

Dave Rolsky, <autarch@urth.org>

BUGS ^

Please report any bugs or feature requests to bug-catalyst-plugin-authencookie@rt.cpan.org, or through the web interface at http://rt.cpan.org. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

COPYRIGHT & LICENSE ^

Copyright 2008 Dave Rolsky, All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

syntax highlighting: