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).

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:

name - optional

The name of the cookie. This defaults to "authen-cookie". It's probably a good idea to set this to something specific to your app.

mac_secret - required

This can be any scalar value. It should be a value that is consistent across application restarts and multiple app servers, as changing this secret will invalidate existing cookies.

You should never reveal to clients, since once it is known it is easy to forge a valid cookie.

path - optional

The path to which the cookie applies. Defaults to /.

secure - optional

This is a boolean indicating whether the cookie is SSL-only or not. Defaults to false.

domain - optional

The domain used for the cookie. By default, this is not set at all, but if your app operates across multiple hostnames in the same domain, you probably want to set this.

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:

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.

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.