-Catalyst-Plugin-Authentication-Store-DBIx-Class
+NAME
+ Catalyst::Plugin::Authentication::Store::DBIx::Class - A storage class
+ for Catalyst Authentication using DBIx::Class
-The README is used to introduce the module and provide instructions on
-how to install the module, any machine dependencies it may have (for
-example C compilers and installed libraries) and any other information
-that should be provided before the module is installed.
+VERSION
+ This documentation refers to version 0.02.
-A README file is required for CPAN modules since CPAN extracts the README
-file from a module distribution so that people browsing the archive
-can use it get an idea of the modules uses. It is usually a good idea
-to provide version information here so that people can decide whether
-fixes for the module are worth downloading.
+SYNOPSIS
+ use Catalyst qw/
+ Authentication
+ Authorization::Roles/;
-INSTALLATION
+ __PACKAGE__->config->{authentication} =
+ {
+ default_realm => 'members',
+ realms => {
+ members => {
+ credential => {
+ class => 'Password',
+ password_field => 'password',
+ password_type => 'clear'
+ },
+ store => {
+ class => 'DBIx::Class',
+ user_class => 'MyApp::Users',
+ id_field => 'user_id',
+ role_relation => 'roles',
+ role_field => 'rolename',
+ }
+ }
+ }
+ };
-To install this module, run the following commands:
+ # Log a user in:
+
+ sub login : Global {
+ my ( $self, $c ) = @_;
+
+ $c->authenticate({
+ username => $c->req->params->username,
+ password => $c->req->params->password,
+ status => [ 'registered', 'loggedin', 'active']
+ }))
+ }
+
+ # verify a role
+
+ if ( $c->check_user_roles( 'editor' ) ) {
+ # do editor stuff
+ }
- perl Makefile.PL
- make
- make test
- make install
+DESCRIPTION
+ The Catalyst::Plugin::Authentication::Store::DBIx::Class class provides
+ access to authentication information stored in a database via
+ DBIx::Class.
+CONFIGURATION
+ The DBIx::Class authentication store is activated by setting the store
+ config's class element to DBIx::Class as shown above. See the
+ Catalyst::Plugin::Authentication documentation for more details on
+ configuring the store.
-SUPPORT AND DOCUMENTATION
+ The DBIx::Class storage module has several configuration options
-After installing, you can find documentation for this module with the perldoc command.
+ __PACKAGE__->config->{authentication} =
+ {
+ default_realm => 'members',
+ realms => {
+ members => {
+ credential => {
+ # ...
+ },
+ store => {
+ class => 'DBIx::Class',
+ user_class => 'MyApp::Users',
+ id_field => 'user_id',
+ role_relation => 'roles',
+ role_field => 'rolename',
+ ignore_fields_in_find => [ 'remote_name' ]
+ }
+ }
+ }
+ };
- perldoc Catalyst::Plugin::Authentication::Store::DBIx::Class
+ class
+ Class is part of the core Catalyst::Authentication::Plugin module,
+ it contains the class name of the store to be used.
-You can also look for information at:
+ user_class
+ Contains the class name (as passed to $c->model()) of the
+ DBIx::Class schema to use as the source for user information. This
+ config item is REQUIRED.
- Search CPAN
- http://search.cpan.org/dist/Catalyst-Plugin-Authentication-Store-DBIx-Class
+ id_field
+ Contains the field name containing the unique identifier for a user.
+ This is used when storing and retrieving a user from the session.
+ The value in this field should correspond to a single user in the
+ database. Defaults to 'id'.
- CPAN Request Tracker:
- http://rt.cpan.org/NoAuth/Bugs.html?Dist=Catalyst-Plugin-Authentication-Store-DBIx-Class
+ role_column
+ If your role information is stored in the same table as the rest of
+ your user information, this item tells the module which field
+ contains your role information. The DBIx::Class authentication store
+ expects the data in this field to be a series of role names
+ separated by some combination of spaces, commas or pipe characters.
- AnnoCPAN, annotated CPAN documentation:
- http://annocpan.org/dist/Catalyst-Plugin-Authentication-Store-DBIx-Class
+ role_relation
+ If your role information is stored in a separate table, this is the
+ name of the relation that will lead to the roles the user is in. If
+ this is specified then a role_field is also required. Also when
+ using this method it is expected that your role table will return
+ one row for each role the user is in.
- CPAN Ratings:
- http://cpanratings.perl.org/d/Catalyst-Plugin-Authentication-Store-DBIx-Class
+ role_field
+ This is the name of the field in the role table that contains the
+ string identifying the role.
-COPYRIGHT AND LICENCE
+ ignore_fields_in_find
+ This item is an array containing fields that may be passed to the
+ $c->authenticate() routine (and therefore find_user in the storage
+ class), but which should be ignored when creating the DBIx::Class
+ search to retrieve a user. This makes it possible to avoid problems
+ when a credential requires an authinfo element whose name overlaps
+ with a column name in your users table. If this doesn't make sense
+ to you, you probably don't need it.
-Copyright (C) 2006 Jay Kuri
+ store_user_class
+ This allows you to override the authentication user class that the
+ DBIx::Class store module uses to perform it's work. Most of the work
+ done in this module is actually done by the user class,
+ Catalyst::Plugin::Authentication::Store::DBIx::Class::User, so
+ overriding this doesn't make much sense unless you are using your
+ own class to extend the functionality of the existing class. Chances
+ are you do not want to set this.
+
+USAGE
+ The Catalyst::Plugin::Authentication::Store::DBIx::Class storage module
+ is not called directly from application code. You interface with it
+ through the $c->authenticate() call.
+
+ There are three methods you can use to retrieve information from the
+ DBIx::Class storage module. They are Simple retrieval, and the advanced
+ retrieval methods Searchargs and Resultset.
+
+ Simple Retrieval
+ The first, and most common, method is simple retrieval. As it's name
+ implies simple retrieval allows you to simply to provide the column =>
+ value pairs that should be used to locate the user in question. An
+ example of this usage is below:
+
+ if ($c->authenticate({
+ username => $c->req->params->{'username'},
+ password => $c->req->params->{'password'},
+ status => [ 'registered', 'active', 'loggedin']
+ })) {
+
+ # ... authenticated user code here
+ }
+
+ The above example would attempt to retrieve a user whose username column
+ matched the username provided, and whose status column matched one of
+ the values provided. These name => value pairs are used more or less
+ directly in the DBIx::Class' search() routine, so in most cases, you can
+ use DBIx::Class syntax to retrieve the user according to whatever rules
+ you have.
+
+ NOTE: Because the password in most cases is encrypted - it is not used
+ directly but it's encryption and comparison with the value provided is
+ usually handled by the Password Credential. Part of the Password
+ Credential's behavior is to remove the password argument from the
+ authinfo that is passed to the storage module. See
+ Catalyst::Plugin::Authentication::Credential::Password.
+
+ One thing you need to know about this retrieval method is that the name
+ portion of the pair is checked against the user class' column list.
+ Pairs are only used if a matching column is found. Other pairs will be
+ ignored. This means that you can only provide simple name-value pairs,
+ and that some more advanced DBIx::Class constructs, such as '-or',
+ '-and', etc. are in most cases not possible using this method. For
+ queries that require this level of functionality, see the 'searchargs'
+ method below.
+
+ Advanced Retrieval
+ The Searchargs and Resultset retrieval methods are used when more
+ advanced features of the underlying DBIx::Class schema are required.
+ These methods provide a direct interface with the DBIx::Class schema and
+ therefore require a better understanding of the DBIx::Class module.
+
+ The dbix_class key
+ Since the format of these arguments are often complex, they are not keys
+ in the base authinfo hash. Instead, both of these arguments are placed
+ within a hash attached to the store-specific 'dbix_class' key in the
+ base $authinfo hash. When the DBIx::Class authentication store sees the
+ 'dbix_class' key in the passed authinfo hash, all the other information
+ in the authinfo hash is ignored and only the values within the
+ 'dbix_class' hash are used as though they were passed directly within
+ the authinfo hash. In other words, if 'dbix_class' is present, it
+ replaces the authinfo hash for processing purposes.
+
+ The 'dbix_class' hash can be used to directly pass arguments to the
+ DBIx::Class authentication store. Reasons to do this are to avoid
+ credential modification of the authinfo hash, or to avoid overlap
+ between credential and store key names. It's a good idea to avoid using
+ it in this way unless you are sure you have an overlap/modification
+ issue. However, the two advanced retrieval methods, searchargs and
+ resultset, require it's use, as they are only processed as part of the
+ 'dbix_class' hash
+
+ Searchargs
+ The searchargs method of retrieval allows you to specify an arrayref
+ containing the two arguments to the search() method from
+ DBIx::Class::Resultset. If provided, all other args are ignored, and
+ the search args provided are used directly to locate the user. An
+ example will probably make more sense:
+
+ if ($c->authenticate(
+ {
+ password => $password,
+ 'dbix_class' =>
+ {
+ searchargs = [ { -or => [ username => $username,
+ email => $email,
+ clientid => $clientid ]
+ },
+ { prefetch => qw/ preferences / }
+ ]
+ }
+ } ) )
+ {
+ # do successful authentication actions here.
+ }
+
+ The above would allow authentication based on any of the three items
+ - username, email or clientid and would prefetch the data related to
+ that user from the preferences table. The searchargs array is passed
+ directly to the search() method associated with the user_class.
+
+ Resultset
+ The resultset method of retrieval allows you to directly specify a
+ resultset to be used for user retrieval. This allows you to create a
+ resultset within your login action and use it for retrieving the
+ user. A simple example:
+
+ my $rs = $c->model('MyApp::User')->search({ email => $c->request->params->{'email'} });
+ ... # further $rs adjustments
+
+ if ($c->authenticate({
+ password => $password,
+ 'dbix_class' => { resultset = $rs }
+ })) {
+ # do successful authentication actions here.
+ }
+
+ Be aware that the resultset method will not verify that you are
+ passing a resultset that is attached to the same user_class as
+ specified in the config.
+
+ NOTE: All of these methods of user retrieval, including the
+ resultset method, consider the first row returned to be the matching
+ user. In most cases there will be only one matching row, but it is
+ easy to produce multiple rows, especially when using the advanced
+ retrieval methods. Remember, what you get when you use this module
+ is what you would get when calling search(...)->first;
+
+ NOTE ALSO: The user info used to save the user to the session and to
+ retrieve it is the same regardless of what method of retrieval was
+ used. In short, the value in the id field (see 'id_field' config
+ item) is used to retrieve the user from the database upon restoring
+ from the session. When the DBIx::Class storage module does this, it
+ does so by doing a simple search using the id field. In other words,
+ it will not use the same arguments you used to request the user
+ initially. This is especially important to those using the advanced
+ methods of user retrieval. If you need more complicated logic when
+ reviving the user from the session, you will most likely want to
+ subclass the
+ Catalyst::Plugin::Authentication::Store::DBIx::Class::User class and
+ provide your own for_session and from_session routines.
+
+METHODS
+ There are no publicly exported routines in the DBIx::Class
+ 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
+ Catalyst::Plugin::Authentication::Store::DBIx::Class::User's load()
+ method.
+
+ for_session ( $c, $user )
+ Prepares a user to be stored in the session. Currently returns the
+ value of the user's id field - (as indicated by the 'id_field'
+ config element)
+
+ from_session ( $c, $frozenuser)
+ Revives a user from the session based on the info provided in
+ $frozenuser. Currently treats $frozenuser as an id and retrieves a
+ user with a matching id.
+
+ user_supports
+ Provides information about what the user object supports.
+
+NOTES
+ As of the current release, session storage consists of simply storing
+ the user's id in the session, and then using that same id to re-retrieve
+ the users information from the database upon restoration from the
+ session. More dynamic storage of user information in the session is
+ intended for a future release.
+
+BUGS AND LIMITATIONS
+ None known currently, please email the author if you find any.
+
+SEE ALSO
+ Catalyst::Plugin::Authentication,
+ Catalyst::Plugin::Authentication::Internals, and
+ Catalyst::Plugin::Authorization::Roles
+
+AUTHOR
+ Jason Kuri (jayk@cpan.org)
+
+LICENSE
+ Copyright (c) 2007 the aforementioned authors. All rights reserved. This
+ program is free software; you can redistribute it and/or modify it under
+ the same terms as Perl itself.
-This program is free software; you can redistribute it and/or modify it
-under the same terms as Perl itself.
projects / catagits/Catalyst-Authentication-Store-DBIx-Class.git / commitdiff