1Catalyst::AuthenticatioUns:e:rStCoornet:rC:iaDbtBuaItlxey:ds:tCP:le:arAslust(Dh3oe)cnutmiecnattaitoino:n:Store::DBIx::Class(3)
2
3
4

NAME

6       Catalyst::Authentication::Store::DBIx::Class - A storage class for
7       Catalyst Authentication using DBIx::Class
8

VERSION

10       This documentation refers to version 0.1506.
11

SYNOPSIS

13           use Catalyst qw/
14                           Authentication
15                           Authorization::Roles/;
16
17           __PACKAGE__->config('Plugin::Authentication' => {
18               default_realm => 'members',
19               realms => {
20                   members => {
21                       credential => {
22                           class => 'Password',
23                           password_field => 'password',
24                           password_type => 'clear'
25                       },
26                       store => {
27                           class => 'DBIx::Class',
28                           user_model => 'MyApp::User',
29                           role_relation => 'roles',
30                           role_field => 'rolename',
31                       }
32                   }
33               }
34           });
35
36           # Log a user in:
37
38           sub login : Global {
39               my ( $self, $ctx ) = @_;
40
41               $ctx->authenticate({
42                                 screen_name => $ctx->req->params->{username},
43                                 password => $ctx->req->params->{password},
44                                 status => [ 'registered', 'loggedin', 'active']
45                                 }))
46           }
47
48           # verify a role
49
50           if ( $ctx->check_user_roles( 'editor' ) ) {
51               # do editor stuff
52           }
53

DESCRIPTION

55       The Catalyst::Authentication::Store::DBIx::Class class provides access
56       to authentication information stored in a database via DBIx::Class.
57

CONFIGURATION

59       The DBIx::Class authentication store is activated by setting the store
60       config's class element to DBIx::Class as shown above. See the
61       Catalyst::Plugin::Authentication documentation for more details on
62       configuring the store. You can also use
63       Catalyst::Authentication::Realm::SimpleDB for a simplified setup.
64
65       The DBIx::Class storage module has several configuration options
66
67           __PACKAGE__->config('Plugin::Authentication' => {
68               default_realm => 'members',
69               realms => {
70                   members => {
71                       credential => {
72                           # ...
73                       },
74                       store => {
75                           class => 'DBIx::Class',
76                           user_model => 'MyApp::User',
77                           role_relation => 'roles',
78                           role_field => 'rolename',
79                           ignore_fields_in_find => [ 'remote_name' ],
80                           use_userdata_from_session => 1,
81                       }
82                   }
83               }
84           });
85
86       class
87           Class is part of the core Catalyst::Plugin::Authentication module;
88           it contains the class name of the store to be used.
89
90       user_model
91           Contains the model name (as passed to "$ctx->model()") of the
92           DBIx::Class schema to use as the source for user information. This
93           config item is REQUIRED.
94
95           (Note that this option used to be called "user_class". "user_class"
96           is still functional, but should be used only for compatibility with
97           previous configs.  The setting called "user_class" on other
98           authentication stores is present, but named "store_user_class" in
99           this store)
100
101       role_column
102           If your role information is stored in the same table as the rest of
103           your user information, this item tells the module which field
104           contains your role information.  The DBIx::Class authentication
105           store expects the data in this field to be a series of role names
106           separated by some combination of spaces, commas, or pipe
107           characters.
108
109       role_relation
110           If your role information is stored in a separate table, this is the
111           name of the relation that will lead to the roles the user is in.
112           If this is specified, then a role_field is also required.  Also
113           when using this method it is expected that your role table will
114           return one row for each role the user is in.
115
116       role_field
117           This is the name of the field in the role table that contains the
118           string identifying the role.
119
120       ignore_fields_in_find
121           This item is an array containing fields that may be passed to the
122           "$ctx->authenticate()" routine (and therefore find_user in the
123           storage class), but which should be ignored when creating the
124           DBIx::Class search to retrieve a user. This makes it possible to
125           avoid problems when a credential requires an authinfo element whose
126           name overlaps with a column name in your users table.  If this
127           doesn't make sense to you, you probably don't need it.
128
129       use_userdata_from_session
130           Under normal circumstances, on each request the user's data is re-
131           retrieved from the database using the primary key for the user
132           table.  When this flag is set in the configuration, it causes the
133           DBIx::Class store to avoid this database hit on session restore.
134           Instead, the user object's column data is retrieved from the
135           session and used as-is.
136
137           NOTE: Since the user object's column data is only stored in the
138           session during the initial authentication of the user, turning this
139           on can potentially lead to a situation where the data in
140           "$ctx->user" is different from what is stored the database.  You
141           can force a reload of the data from the database at any time by
142           calling "$ctx->user->get_object(1);" Note that this will update
143           "$ctx->user" for the remainder of this request.  It will NOT update
144           the session.  If you need to update the session you should call
145           "$ctx->update_user_in_session()" as well.
146
147       store_user_class
148           This allows you to override the authentication user class that the
149           DBIx::Class store module uses to perform its work.  Most of the
150           work done in this module is actually done by the user class,
151           Catalyst::Authentication::Store::DBIx::Class::User, so overriding
152           this doesn't make much sense unless you are using your own class to
153           extend the functionality of the existing class.  Chances are you do
154           not want to set this.
155
156       id_field
157           In most cases, this config variable does not need to be set, as
158           Catalyst::Authentication::Store::DBIx::Class will determine the
159           primary key of the user table on its own.  If you need to override
160           the default, or your user table has multiple primary keys, then
161           id_field should contain the column name that should be used to
162           restore the user.  A given value in this column should correspond
163           to a single user in the database.  Note that this is used ONLY when
164           restoring a user from the session and has no bearing whatsoever in
165           the initial authentication process.  Note also that if
166           use_userdata_from_session is enabled, this config parameter is not
167           used at all.
168

USAGE

170       The Catalyst::Authentication::Store::DBIx::Class storage module is not
171       called directly from application code.  You interface with it through
172       the $ctx->authenticate() call.
173
174       There are three methods you can use to retrieve information from the
175       DBIx::Class storage module.  They are Simple retrieval, and the
176       advanced retrieval methods Searchargs and Resultset.
177
178   Simple Retrieval
179       The first, and most common, method is simple retrieval. As its name
180       implies simple retrieval allows you to simply to provide the column =>
181       value pairs that should be used to locate the user in question. An
182       example of this usage is below:
183
184           if ($ctx->authenticate({
185                                 screen_name => $ctx->req->params->{'username'},
186                                 password => $ctx->req->params->{'password'},
187                                 status => [ 'registered', 'active', 'loggedin']
188                                })) {
189
190               # ... authenticated user code here
191           }
192
193       The above example would attempt to retrieve a user whose username
194       column (here, screen_name) matched the username provided, and whose
195       status column matched one of the values provided. These name => value
196       pairs are used more or less directly in the DBIx::Class search()
197       routine, so in most cases, you can use DBIx::Class syntax to retrieve
198       the user according to whatever rules you have.
199
200       NOTE: Because the password in most cases is encrypted - it is not used
201       directly but its encryption and comparison with the value provided is
202       usually handled by the Password Credential. Part of the Password
203       Credential's behavior is to remove the password argument from the
204       authinfo that is passed to the storage module. See
205       Catalyst::Authentication::Credential::Password.
206
207       One thing you need to know about this retrieval method is that the name
208       portion of the pair is checked against the user class's column list.
209       Pairs are only used if a matching column is found. Other pairs will be
210       ignored. This means that you can only provide simple name-value pairs,
211       and that some more advanced DBIx::Class constructs, such as '-or',
212       '-and', etc. are in most cases not possible using this method. For
213       queries that require this level of functionality, see the 'searchargs'
214       method below.
215
216   Advanced Retrieval
217       The Searchargs and Resultset retrieval methods are used when more
218       advanced features of the underlying DBIx::Class schema are required.
219       These methods provide a direct interface with the DBIx::Class schema
220       and therefore require a better understanding of the DBIx::Class module.
221
222       The dbix_class key
223
224       Since the format of these arguments are often complex, they are not
225       keys in the base authinfo hash.  Instead, both of these arguments are
226       placed within a hash attached to the store-specific 'dbix_class' key in
227       the base $authinfo hash.  When the DBIx::Class authentication store
228       sees the 'dbix_class' key in the passed authinfo hash, all the other
229       information in the authinfo hash is ignored and only the values within
230       the 'dbix_class' hash are used as though they were passed directly
231       within the authinfo hash.  In other words, if 'dbix_class' is present,
232       it replaces the authinfo hash for processing purposes.
233
234       The 'dbix_class' hash can be used to directly pass arguments to the
235       DBIx::Class authentication store. Reasons to do this are to avoid
236       credential modification of the authinfo hash, or to avoid overlap
237       between credential and store key names. It's a good idea to avoid using
238       it in this way unless you are sure you have an overlap/modification
239       issue. However, the two advanced retrieval methods, searchargs, result
240       and resultset, require its use, as they are only processed as part of
241       the 'dbix_class' hash.
242
243       Searchargs
244           The searchargs method of retrieval allows you to specify an
245           arrayref containing the two arguments to the search() method from
246           DBIx::Class::ResultSet.  If provided, all other args are ignored,
247           and the search args provided are used directly to locate the user.
248           An example will probably make more sense:
249
250               if ($ctx->authenticate(
251                   {
252                       password => $password,
253                       'dbix_class' =>
254                           {
255                               searchargs => [ { -or => [ username => $username,
256                                                         email => $email,
257                                                         clientid => $clientid ]
258                                              },
259                                              { prefetch => qw/ preferences / }
260                                            ]
261                           }
262                   } ) )
263               {
264                   # do successful authentication actions here.
265               }
266
267           The above would allow authentication based on any of the three
268           items - username, email, or clientid - and would prefetch the data
269           related to that user from the preferences table. The searchargs
270           array is passed directly to the search() method associated with the
271           user_model.
272
273       Result
274           The result method of retrieval allows you to look up the user
275           yourself and pass on the loaded user to the authentication store.
276
277               my $user = $ctx->model('MyApp::User')->find({ ... });
278
279               if ($ctx->authenticate({ dbix_class => { result => $user } })) {
280                   ...
281               }
282
283           Be aware that the result method will not verify that you are
284           passing a result that is attached to the same user_model as
285           specified in the config or even loaded from the database, as
286           opposed to existing only in memory. It's your responsibility to
287           make sure of that.
288
289       Resultset
290           The resultset method of retrieval allows you to directly specify a
291           resultset to be used for user retrieval. This allows you to create
292           a resultset within your login action and use it for retrieving the
293           user. A simple example:
294
295               my $rs = $ctx->model('MyApp::User')->search({ email => $ctx->request->params->{'email'} });
296                  ... # further $rs adjustments
297
298               if ($ctx->authenticate({
299                                      password => $password,
300                                      'dbix_class' => { resultset => $rs }
301                                    })) {
302                  # do successful authentication actions here.
303               }
304
305           Be aware that the resultset method will not verify that you are
306           passing a resultset that is attached to the same user_model as
307           specified in the config.
308
309           NOTE: The resultset and searchargs methods of user retrieval,
310           consider the first row returned to be the matching user. In most
311           cases there will be only one matching row, but it is easy to
312           produce multiple rows, especially when using the advanced retrieval
313           methods. Remember, what you get when you use this module is what
314           you would get when calling search(...)->first;
315
316           NOTE ALSO:  The user info used to save the user to the session and
317           to retrieve it is the same regardless of what method of retrieval
318           was used.  In short, the value in the id field (see 'id_field'
319           config item) is used to retrieve the user from the database upon
320           restoring from the session.  When the DBIx::Class storage module
321           does this, it does so by doing a simple search using the id field.
322           In other words, it will not use the same arguments you used to
323           request the user initially.  This is especially important to those
324           using the advanced methods of user retrieval.  If you need more
325           complicated logic when reviving the user from the session, you will
326           most likely want to subclass the
327           Catalyst::Authentication::Store::DBIx::Class::User class and
328           provide your own for_session and from_session routines.
329

METHODS

331       There are no publicly exported routines in the DBIx::Class
332       authentication store (or indeed in most authentication stores).
333       However, below is a description of the routines required by
334       Catalyst::Plugin::Authentication for all authentication stores.  Please
335       see the documentation for Catalyst::Plugin::Authentication::Internals
336       for more information.
337
338   new ( $config, $app )
339       Constructs a new store object.
340
341   find_user ( $authinfo, $c )
342       Finds a user using the information provided in the $authinfo hashref
343       and returns the user, or undef on failure. This is usually called from
344       the Credential. This translates directly to a call to
345       Catalyst::Authentication::Store::DBIx::Class::User's load() method.
346
347   for_session ( $c, $user )
348       Prepares a user to be stored in the session. Currently returns the
349       value of the user's id field (as indicated by the 'id_field' config
350       element)
351
352   from_session ( $c, $frozenuser)
353       Revives a user from the session based on the info provided in
354       $frozenuser.  Currently treats $frozenuser as an id and retrieves a
355       user with a matching id.
356
357   user_supports
358       Provides information about what the user object supports.
359
360   auto_update_user( $authinfo, $c, $res )
361       This method is called if the realm's auto_update_user setting is true.
362       It will delegate to the user object's "auto_update" method.
363
364   auto_create_user( $authinfo, $c )
365       This method is called if the realm's auto_create_user setting is true.
366       It will delegate to the user class's (resultset) "auto_create" method.
367

NOTES

369       As of the current release, session storage consists of simply storing
370       the user's id in the session, and then using that same id to re-
371       retrieve the user's information from the database upon restoration from
372       the session.  More dynamic storage of user information in the session
373       is intended for a future release.
374

BUGS AND LIMITATIONS

376       None known currently; please email the author if you find any.
377

SEE ALSO

379       Catalyst::Plugin::Authentication,
380       Catalyst::Plugin::Authentication::Internals, and
381       Catalyst::Plugin::Authorization::Roles
382

AUTHOR

384       Jason Kuri (jayk@cpan.org)
385

LICENSE

387       Copyright (c) 2007 the aforementioned authors. All rights reserved.
388       This program is free software; you can redistribute it and/or modify it
389       under the same terms as Perl itself.
390
391
392
393perl v5.36.0                   Cat2a0l2y2s-t0:7:-A2u2thentication::Store::DBIx::Class(3)
Impressum