X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FPlugin%2FAuthentication%2FStore%2FDBIx%2FClass.pm;h=98618b8c4dfa4b5d105bb933c988977408c9175d;hb=ad93b3e931404c862c36e5a6a0955290bafe0998;hp=1ecbe68244dfd43117635ea70794582f818ecf1e;hpb=edb40fe09b700520feef073670c7063273d43e06;p=catagits%2FCatalyst-Authentication-Store-DBIx-Class.git diff --git a/lib/Catalyst/Plugin/Authentication/Store/DBIx/Class.pm b/lib/Catalyst/Plugin/Authentication/Store/DBIx/Class.pm index 1ecbe68..98618b8 100644 --- a/lib/Catalyst/Plugin/Authentication/Store/DBIx/Class.pm +++ b/lib/Catalyst/Plugin/Authentication/Store/DBIx/Class.pm @@ -4,7 +4,11 @@ use strict; use warnings; use base qw/Class::Accessor::Fast/; -our $VERSION= "0.02"; +<<<<<<< .mine +our $VERSION= "0.10"; +======= +our $VERSION= "0.03"; +>>>>>>> .r6516 BEGIN { __PACKAGE__->mk_accessors(qw/config/); @@ -80,69 +84,334 @@ Catalyst::Plugin::Authentication::Store::DBIx::Class - A storage class for Catal =head1 VERSION -This documentation refers to version 0.01. +This documentation refers to version 0.10. =head1 SYNOPSIS -use Catalyst::Plugin::Authentication::Store::DBIx::Class; - + use Catalyst qw/ + Authentication + Authorization::Roles/; + + __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', + } + } + } + }; + + # 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 + } + =head1 DESCRIPTION -The Catalyst::Plugin::Authentication::Store::DBIx::Class class implements ... +The Catalyst::Plugin::Authentication::Store::DBIx::Class class provides +access to authentication information stored in a database via DBIx::Class. -=head1 SUBROUTINES / METHODS +=head1 CONFIGURATION -=head2 new (constructor) +The DBIx::Class authentication store is activated by setting the store +config's B element to DBIx::Class as shown above. See the +L documentation for more details on +configuring the store. -Parameters: - class - config - app +The DBIx::Class storage module has several configuration options -Insert description of constructor here... -=head2 from_session (method) + __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' ] + } + } + } + }; -Parameters: - c - frozenuser +=over 4 -Insert description of method here... +=item class -=head2 for_session (method) +Class is part of the core Catalyst::Authentication::Plugin module, it +contains the class name of the store to be used. -Parameters: - c - user +=item user_class -Insert description of method here... +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 B. -=head2 find_user (method) +=item id_field -Parameters: - authinfo - c +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'. -Insert description of method here... +=item role_column -=head2 user_supports +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. + +=item 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. + +=item role_field -Parameters: - none +This is the name of the field in the role table that contains the string +identifying the role. + +=item ignore_fields_in_find -Insert description of subroutine here... +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. + +=item 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, +L, 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. + +=back + +=head1 USAGE + +The L 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. + +=head2 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 L. + +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. + +=head2 Advanced Retrieval + +The Searchargs and Resultset retrieval methods are used when more advanced +features of the underlying L 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. + +=head3 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, B and B, require it's use, as they +are only processed as part of the 'dbix_class' hash + +=over 4 + +=item Searchargs + +The B method of retrieval allows you to specify an arrayref containing +the two arguments to the search() method from L. 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. + +=item Resultset + +The B 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 L class +and provide your own for_session and from_session routines. + +=back + + +=head1 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 L +for all authentication stores. Please see the documentation for +L for more information. + +=over 4 + +=item new ( $config, $app ) + +Constructs a new store object. + +=item 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 +L's load() method. -=head1 DEPENDENCIES +=item for_session ( $c, $user ) -Modules used, version dependencies, core yes/no +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) -strict +=item from_session ( $c, $frozenuser) -warnings +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. + +=item user_supports + +Provides information about what the user object supports. + +=back =head1 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. =head1 BUGS AND LIMITATIONS @@ -150,16 +419,17 @@ None known currently, please email the author if you find any. =head1 SEE ALSO -L, L +L, L, +and L =head1 AUTHOR Jason Kuri (jayk@cpan.org) -=head1 LICENCE - -Copyright 2006 by Jason Kuri. +=head1 LICENSE -This software is free. It is licensed under the same terms as Perl itself. +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. =cut