1Catalyst::AuthenticatioUns:e:rStCoornet:rC:iaDbtBuaItlxey:ds:tCP:le:arAslust(Dh3oe)cnutmiecnattaitoino:n:Store::DBIx::Class(3)
2
6 Catalyst::Authentication::Store::DBIx::Class - A storage class for
7 Catalyst Authentication using DBIx::Class
8
10 This documentation refers to version 0.1506.
11
13 use Catalyst qw/
14 Authentication
15 Authorization::Roles/;
16 __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 # Log a user in:
37 sub login : Global {
39 my ( $self, $ctx ) = @_;
40 $ctx->authenticate({
42 screen_name => $ctx->req->params->{username},
43 password => $ctx->req->params->{password},
44 status => [ 'registered', 'loggedin', 'active']
45 }))
46 }
47 # verify a role
49 if ( $ctx->check_user_roles( 'editor' ) ) {
51 # do editor stuff
52 }
53
55 The Catalyst::Authentication::Store::DBIx::Class class provides access
56 to authentication information stored in a database via DBIx::Class.
57
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 The DBIx::Class storage module has several configuration options
66 __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 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 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 (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 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 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 role_field
117 This is the name of the field in the role table that contains the
118 string identifying the role.
119 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 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 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 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 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
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 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 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 if ($ctx->authenticate({
185 screen_name => $ctx->req->params->{'username'},
186 password => $ctx->req->params->{'password'},
187 status => [ 'registered', 'active', 'loggedin']
188 })) {
189 # ... authenticated user code here
191 }
192 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 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 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 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 The dbix_class key
223 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 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 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 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 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 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 my $user = $ctx->model('MyApp::User')->find({ ... });
278 if ($ctx->authenticate({ dbix_class => { result => $user } })) {
280 ...
281 }
282 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 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 my $rs = $ctx->model('MyApp::User')->search({ email => $ctx->request->params->{'email'} });
296 ... # further $rs adjustments
297 if ($ctx->authenticate({
299 password => $password,
300 'dbix_class' => { resultset => $rs }
301 })) {
302 # do successful authentication actions here.
303 }
304 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 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 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
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 new ( $config, $app )
339 Constructs a new store object.
340 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 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 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 user_supports
358 Provides information about what the user object supports.
359 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 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
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
376 None known currently; please email the author if you find any.
377
379 Catalyst::Plugin::Authentication,
380 Catalyst::Plugin::Authentication::Internals, and
381 Catalyst::Plugin::Authorization::Roles
382
384 Jason Kuri (jayk@cpan.org)
385
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.
390perl v5.30.1 Cat2a0l2y0s-t0:1:-A2u9thentication::Store::DBIx::Class(3)