1 package Catalyst::Authentication::Store::DBIx::Class;
5 use base qw/Class::Accessor::Fast/;
11 __PACKAGE__->mk_accessors(qw/config/);
16 my ( $class, $config, $app ) = @_;
18 ## figure out if we are overriding the default store user class
19 $config->{'store_user_class'} = (exists($config->{'store_user_class'})) ? $config->{'store_user_class'} :
20 "Catalyst::Authentication::Store::DBIx::Class::User";
22 ## make sure the store class is loaded.
23 Catalyst::Utils::ensure_class_loaded( $config->{'store_user_class'} );
25 ## fields can be specified to be ignored during user location. This allows
26 ## the store to ignore certain fields in the authinfo hash.
28 $config->{'ignore_fields_in_find'} ||= [ ];
39 ## let's use DBIC's get_columns method to return a hash and save / restore that
40 ## from the session. Then we can respond to get() calls, etc. in most cases without
41 ## resorting to a DB call. If user_object is called, THEN we can hit the DB and
42 ## return a real object.
44 my ( $self, $c, $frozenuser ) = @_;
46 # return $frozenuser if ref $frozenuser;
48 my $user = $self->config->{'store_user_class'}->new($self->{'config'}, $c);
49 return $user->from_session($frozenuser, $c);
53 my ($self, $c, $user) = @_;
55 return $user->for_session($c);
59 my ( $self, $authinfo, $c ) = @_;
61 my $user = $self->config->{'store_user_class'}->new($self->{'config'}, $c);
63 return $user->load($authinfo, $c);
69 # this can work as a class method on the user class
70 $self->config->{'store_user_class'}->supports( @_ );
73 sub auto_create_user {
74 my( $self, $authinfo, $c ) = @_;
75 my $res = $self->config->{'store_user_class'}->new($self->{'config'}, $c);
76 return $res->auto_create( $authinfo, $c );
79 sub auto_update_user {
80 my( $self, $authinfo, $c, $res ) = @_;
81 $res->auto_update( $authinfo, $c );
91 Catalyst::Authentication::Store::DBIx::Class - A storage class for Catalyst Authentication using DBIx::Class
95 This documentation refers to version 0.10.
101 Authorization::Roles/;
103 __PACKAGE__->config->{authentication} =
105 default_realm => 'members',
110 password_field => 'password',
111 password_type => 'clear'
114 class => 'DBIx::Class',
115 user_class => 'MyApp::User',
116 role_relation => 'roles',
117 role_field => 'rolename',
126 my ( $self, $c ) = @_;
129 screen_name => $c->req->params->username,
130 password => $c->req->params->password,
131 status => [ 'registered', 'loggedin', 'active']
137 if ( $c->check_user_roles( 'editor' ) ) {
143 The Catalyst::Authentication::Store::DBIx::Class class provides
144 access to authentication information stored in a database via DBIx::Class.
148 The DBIx::Class authentication store is activated by setting the store
149 config's B<class> element to DBIx::Class as shown above. See the
150 L<Catalyst::Plugin::Authentication> documentation for more details on
151 configuring the store.
153 The DBIx::Class storage module has several configuration options
156 __PACKAGE__->config->{authentication} =
158 default_realm => 'members',
165 class => 'DBIx::Class',
166 user_class => 'MyApp::User',
167 role_relation => 'roles',
168 role_field => 'rolename',
169 ignore_fields_in_find => [ 'remote_name' ],
170 use_userdata_from_session => 1,
180 Class is part of the core Catalyst::Plugin::Authentication module; it
181 contains the class name of the store to be used.
185 Contains the class name (as passed to $c->model()) of the DBIx::Class schema
186 to use as the source for user information. This config item is B<REQUIRED>.
190 If your role information is stored in the same table as the rest of your user
191 information, this item tells the module which field contains your role
192 information. The DBIx::Class authentication store expects the data in this
193 field to be a series of role names separated by some combination of spaces,
194 commas, or pipe characters.
198 If your role information is stored in a separate table, this is the name of
199 the relation that will lead to the roles the user is in. If this is
200 specified, then a role_field is also required. Also when using this method
201 it is expected that your role table will return one row for each role
206 This is the name of the field in the role table that contains the string
207 identifying the role.
209 =item ignore_fields_in_find
211 This item is an array containing fields that may be passed to the
212 $c->authenticate() routine (and therefore find_user in the storage class), but
213 which should be ignored when creating the DBIx::Class search to retrieve a
214 user. This makes it possible to avoid problems when a credential requires an
215 authinfo element whose name overlaps with a column name in your users table.
216 If this doesn't make sense to you, you probably don't need it.
218 =item use_userdata_from_session
220 Under normal circumstances, on each request the user's data is re-retrieved
221 from the database using the primary key for the user table. When this flag
222 is set in the configuration, it causes the DBIx::Class store to avoid this
223 database hit on session restore. Instead, the user object's column data
224 is retrieved from the session and used as-is.
226 B<NOTE>: Since the user object's column
227 data is only stored in the session during the initial authentication of
228 the user, turning this on can potentially lead to a situation where the data
229 in $c->user is different from what is stored the database. You can force
230 a reload of the data from the database at any time by calling $c->user->get_object(1);
231 Note that this will update $c->user for the remainder of this request.
232 It will NOT update the session. If you need to update the session
233 you should call $c->update_user_in_session() as well.
235 =item store_user_class
237 This allows you to override the authentication user class that the
238 DBIx::Class store module uses to perform its work. Most of the
239 work done in this module is actually done by the user class,
240 L<Catalyst::Authentication::Store::DBIx::Class::User>, so
241 overriding this doesn't make much sense unless you are using your
242 own class to extend the functionality of the existing class.
243 Chances are you do not want to set this.
247 In most cases, this config variable does not need to be set, as
248 Catalyst::Authentication::Store::DBIx::Class will determine the primary
249 key of the user table on its own. If you need to override the default,
250 or your user table has multiple primary keys, then id_field
251 should contain the column name that should be used to restore the user.
252 A given value in this column should correspond to a single user in the database.
253 Note that this is used B<ONLY> when restoring a user from the session and
254 has no bearing whatsoever in the initial authentication process. Note also
255 that if use_userdata_from_session is enabled, this config parameter
262 The L<Catalyst::Authentication::Store::DBIx::Class> storage module
263 is not called directly from application code. You interface with it
264 through the $c->authenticate() call.
266 There are three methods you can use to retrieve information from the DBIx::Class
267 storage module. They are Simple retrieval, and the advanced retrieval methods
268 Searchargs and Resultset.
270 =head2 Simple Retrieval
272 The first, and most common, method is simple retrieval. As its name implies
273 simple retrieval allows you to simply to provide the column => value pairs
274 that should be used to locate the user in question. An example of this usage
277 if ($c->authenticate({
278 screen_name => $c->req->params->{'username'},
279 password => $c->req->params->{'password'},
280 status => [ 'registered', 'active', 'loggedin']
283 # ... authenticated user code here
286 The above example would attempt to retrieve a user whose username column (here,
287 screen_name) matched the username provided, and whose status column matched one of the
288 values provided. These name => value pairs are used more or less directly in
289 the DBIx::Class search() routine, so in most cases, you can use DBIx::Class
290 syntax to retrieve the user according to whatever rules you have.
292 NOTE: Because the password in most cases is encrypted - it is not used
293 directly but its encryption and comparison with the value provided is usually
294 handled by the Password Credential. Part of the Password Credential's behavior
295 is to remove the password argument from the authinfo that is passed to the
296 storage module. See L<Catalyst::Authentication::Credential::Password>.
298 One thing you need to know about this retrieval method is that the name
299 portion of the pair is checked against the user class's column list. Pairs are
300 only used if a matching column is found. Other pairs will be ignored. This
301 means that you can only provide simple name-value pairs, and that some more
302 advanced DBIx::Class constructs, such as '-or', '-and', etc. are in most cases
303 not possible using this method. For queries that require this level of
304 functionality, see the 'searchargs' method below.
306 =head2 Advanced Retrieval
308 The Searchargs and Resultset retrieval methods are used when more advanced
309 features of the underlying L<DBIx::Class> schema are required. These methods
310 provide a direct interface with the DBIx::Class schema and therefore
311 require a better understanding of the DBIx::Class module.
313 =head3 The dbix_class key
315 Since the format of these arguments are often complex, they are not keys in
316 the base authinfo hash. Instead, both of these arguments are placed within
317 a hash attached to the store-specific 'dbix_class' key in the base $authinfo
318 hash. When the DBIx::Class authentication store sees the 'dbix_class' key
319 in the passed authinfo hash, all the other information in the authinfo hash
320 is ignored and only the values within the 'dbix_class' hash are used as
321 though they were passed directly within the authinfo hash. In other words, if
322 'dbix_class' is present, it replaces the authinfo hash for processing purposes.
324 The 'dbix_class' hash can be used to directly pass arguments to the
325 DBIx::Class authentication store. Reasons to do this are to avoid credential
326 modification of the authinfo hash, or to avoid overlap between credential and
327 store key names. It's a good idea to avoid using it in this way unless you are
328 sure you have an overlap/modification issue. However, the two advanced
329 retrieval methods, B<searchargs> and B<resultset>, require its use, as they
330 are only processed as part of the 'dbix_class' hash.
336 The B<searchargs> method of retrieval allows you to specify an arrayref containing
337 the two arguments to the search() method from L<DBIx::Class::ResultSet>. If provided,
338 all other args are ignored, and the search args provided are used directly to locate
339 the user. An example will probably make more sense:
341 if ($c->authenticate(
343 password => $password,
346 searchargs => [ { -or => [ username => $username,
348 clientid => $clientid ]
350 { prefetch => qw/ preferences / }
355 # do successful authentication actions here.
358 The above would allow authentication based on any of the three items -
359 username, email, or clientid - and would prefetch the data related to that user
360 from the preferences table. The searchargs array is passed directly to the
361 search() method associated with the user_class.
365 The B<resultset> method of retrieval allows you to directly specify a
366 resultset to be used for user retrieval. This allows you to create a resultset
367 within your login action and use it for retrieving the user. A simple example:
369 my $rs = $c->model('MyApp::User')->search({ email => $c->request->params->{'email'} });
370 ... # further $rs adjustments
372 if ($c->authenticate({
373 password => $password,
374 'dbix_class' => { resultset => $rs }
376 # do successful authentication actions here.
379 Be aware that the resultset method will not verify that you are passing a
380 resultset that is attached to the same user_class as specified in the config.
382 NOTE: All of these methods of user retrieval, including the resultset method,
383 consider the first row returned to be the matching user. In most cases there
384 will be only one matching row, but it is easy to produce multiple rows,
385 especially when using the advanced retrieval methods. Remember, what you get
386 when you use this module is what you would get when calling
389 NOTE ALSO: The user info used to save the user to the session and to retrieve
390 it is the same regardless of what method of retrieval was used. In short,
391 the value in the id field (see 'id_field' config item) is used to retrieve the
392 user from the database upon restoring from the session. When the DBIx::Class storage
393 module does this, it does so by doing a simple search using the id field. In other
394 words, it will not use the same arguments you used to request the user initially.
395 This is especially important to those using the advanced methods of user retrieval.
396 If you need more complicated logic when reviving the user from the session, you will
397 most likely want to subclass the L<Catalyst::Authentication::Store::DBIx::Class::User> class
398 and provide your own for_session and from_session routines.
405 There are no publicly exported routines in the DBIx::Class authentication
406 store (or indeed in most authentication stores). However, below is a
407 description of the routines required by L<Catalyst::Plugin::Authentication>
408 for all authentication stores. Please see the documentation for
409 L<Catalyst::Plugin::Authentication::Internals> for more information.
412 =head2 new ( $config, $app )
414 Constructs a new store object.
416 =head2 find_user ( $authinfo, $c )
418 Finds a user using the information provided in the $authinfo hashref and
419 returns the user, or undef on failure. This is usually called from the
420 Credential. This translates directly to a call to
421 L<Catalyst::Authentication::Store::DBIx::Class::User>'s load() method.
423 =head2 for_session ( $c, $user )
425 Prepares a user to be stored in the session. Currently returns the value of
426 the user's id field (as indicated by the 'id_field' config element)
428 =head2 from_session ( $c, $frozenuser)
430 Revives a user from the session based on the info provided in $frozenuser.
431 Currently treats $frozenuser as an id and retrieves a user with a matching id.
435 Provides information about what the user object supports.
437 =head2 auto_update_user( $authinfo, $c, $res )
439 This method is called if the realm's auto_update_user setting is true. It
440 will delegate to the user object's C<auto_update> method.
442 =head2 auto_create_user( $authinfo, $c )
444 This method is called if the realm's auto_create_user setting is true. It
445 will delegate to the user class's (resultset) C<auto_create> method.
449 As of the current release, session storage consists of simply storing the user's
450 id in the session, and then using that same id to re-retrieve the user's information
451 from the database upon restoration from the session. More dynamic storage of
452 user information in the session is intended for a future release.
454 =head1 BUGS AND LIMITATIONS
456 None known currently; please email the author if you find any.
460 L<Catalyst::Plugin::Authentication>, L<Catalyst::Plugin::Authentication::Internals>,
461 and L<Catalyst::Plugin::Authorization::Roles>
465 Jason Kuri (jayk@cpan.org)
469 Copyright (c) 2007 the aforementioned authors. All rights
470 reserved. This program is free software; you can redistribute
471 it and/or modify it under the same terms as Perl itself.