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.