NAME

Catalyst::Authentication::Store::CouchDB - A storage class for Catalyst Authentication using CouchDB

VERSION

version 0.001

SYNOPSIS

    use Catalyst qw/
                    Authentication
                    Authorization::Roles/;

    __PACKAGE__->config->{authentication} =
                    {
                        default_realm => 'members',
                        realms => {
                            members => {
                                credential => {
                                    class => 'Password',
                                    password_field => 'password',
                                    password_type => 'salted_hash',
                                    password_salt_len => 4,
                                },
                                store => {
                                    class       => 'CouchDB',
                                    couchdb_uri => 'http://localhost:5984',
                                    dbname      => 'demouser',
                                    designdoc   => '_design/user',
                                    view        => 'user',
                                },
                            },
                        },
                    };

    # Log a user in:

    sub login : Global {
        my ( $self, $c ) = @_;

        $c->authenticate({
                          username => $c->req->params->{username},
                          password => $c->req->params->{password},
                          }))
    }

    # verify a role

    if ( $c->check_user_roles( 'editor' ) ) {
        # do editor stuff
    }

DESCRIPTION

The Catalyst::Authentication::Store::CouchDB class provides access to authentication information stored in a CouchDB instance.

CONFIGURATION

The CouchDB authentication store is activated by setting the store config's class element to CouchDB as shown above. See the Catalyst::Plugin::Authentication documentation for more details on configuring the store.

The CouchDB storage module has several configuration options

    __PACKAGE__->config->{authentication} =
                    {                      
                        default_realm => 'members',
                        realms => {
                            members => {
                                credential => {
                                    class => 'Password',
                                    password_field => 'password',
                                    password_type => 'clear'
                                },
                            store => {
                                class       => 'CouchDB',
                                couchdb_uri => 'http://localhost:5984',
                                dbname      => 'demouser',
                                designdoc   => '_design/user',
                                view        => 'user',
                            },
                        },
                    },
                };

class

Class is part of the core Catalyst::Plugin::Authentication module; it contains the class name of the store to be used. This config item is REQUIRED.

couchdb_uri

Contains the URI of the CouchDB instance to query. This config item is REQUIRED.

dbname

Contains the name of the database to query. This config item is REQUIRED.

designdoc

Contains the name of the CouchDB design document to query. This config item is REQUIRED.

view

Contains the name of the view in the design document to query. The 'username' field will be used as the key to query, and the first document retrieved will be used to create the user model. This config item is REQUIRED.

ua

Contains the name of a class to be used for the User Agent. This defaults to LWP::UserAgent if not configured. It is passed through to CouchDB::Client.

USAGE

The Catalyst::Authentication::Store::CouchDB storage module is not called directly from application code. You interface with it through the $c->authenticate() call.

The Catalyst::Authentication::Store::CouchDB fetches a user from CouchDB by querying a view within a CouchDB design document. The view is queried with the username passed in the authenticate call hash as the key, and returns a CouchDB document. This document is then passed to Catalyst::Authentication::Store::CouchDB::User to create the user object.

A suitable view map function is

        function(doc) {
            if (doc.username) {
                emit(doc.username, null);
            }
        }

METHODS

There are no publicly exported routines in the CouchDB authentication store (or indeed in most authentication stores). However, below is a description of the routines required by Catalyst::Plugin::Authentication for all authentication stores. Please see the documentation for Catalyst::Plugin::Authentication::Internals for more information.

new ( $config, $app )

Constructs a new store object.

find_user ( $authinfo, $c )

Finds a user using the information provided in the $authinfo hashref and returns the user, or undef on failure. This is usually called from the Credential. This translates directly to a call to the User object's load() method.

for_session ( $c, $user )

Prepares a user to be stored in the session. This is delegated to the User obect for_session method.

from_session ( $c, $frozenuser)

Revives a user from the session based on the info provided in $frozenuser. This is delegated to the User object from_session method.

user_supports

Provides information about what the user object supports.

NOTES

This module is heavily based on Catalyst::Authentication::Store::DBIx::Class.

The test scripts use clear text passwords. DO NOT DO THIS IN PRODUCTION. Use configuation as shown in the synopsis to use something stronger, such as salted hash passwords.

The test scripts do not connect to a CouchDB instance as standard - they mock the responses that CouchDB would send. To connect to a CouchDB instance, set the CATALYST_COUCHDB_LIVE environment variable before running the test suite. The test suite assumes that a demouser database exists, with a design document called user that contains a user view, and that a document listing a test user with username test and password test exists. To configure this, run the setup_database.pl script in the t/script directory on the distribution. This script will remove any existing demouser database.

BUGS AND LIMITATIONS

There are bound to be bugs - please email the author if you find any.

SEE ALSO

Catalyst::Authentication::Store::DBIx::Class. Catalyst::Plugin::Authentication, Catalyst::Plugin::Authentication::Internals, and Catalyst::Plugin::Authorization::Roles

AUTHOR

Colin Bradford <cjbradford@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by Colin Bradford.

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

cpanm Catalyst::Authentication::Store::CouchDB

perl -MCPAN -e shell
install Catalyst::Authentication::Store::CouchDB