Debian Codegraph @

README

raw
1 NAME
2 Catalyst::Authentication::Store::DBIx::Class - A storage class for
3 Catalyst Authentication using DBIx::Class
4
5 VERSION
6 This documentation refers to version 0.1506.
7
8 SYNOPSIS
9 use Catalyst qw/
10 Authentication
11 Authorization::Roles/;
12
13 __PACKAGE__->config('Plugin::Authentication' => {
14 default_realm => 'members',
15 realms => {
16 members => {
17 credential => {
18 class => 'Password',
19 password_field => 'password',
20 password_type => 'clear'
21 },
22 store => {
23 class => 'DBIx::Class',
24 user_model => 'MyApp::User',
25 role_relation => 'roles',
26 role_field => 'rolename',
27 }
28 }
29 }
30 });
31
32 # Log a user in:
33
34 sub login : Global {
35 my ( $self, $ctx ) = @_;
36
37 $ctx->authenticate({
38 screen_name => $ctx->req->params->{username},
39 password => $ctx->req->params->{password},
40 status => [ 'registered', 'loggedin', 'active']
41 }))
42 }
43
44 # verify a role
45
46 if ( $ctx->check_user_roles( 'editor' ) ) {
47 # do editor stuff
48 }
49
50 DESCRIPTION
51 The Catalyst::Authentication::Store::DBIx::Class class provides access
52 to authentication information stored in a database via DBIx::Class.
53
54 CONFIGURATION
55 The DBIx::Class authentication store is activated by setting the store
56 config's class element to DBIx::Class as shown above. See the
57 Catalyst::Plugin::Authentication documentation for more details on
58 configuring the store. You can also use
59 Catalyst::Authentication::Realm::SimpleDB for a simplified setup.
60
61 The DBIx::Class storage module has several configuration options
62
63 __PACKAGE__->config('Plugin::Authentication' => {
64 default_realm => 'members',
65 realms => {
66 members => {
67 credential => {
68 # ...
69 },
70 store => {
71 class => 'DBIx::Class',
72 user_model => 'MyApp::User',
73 role_relation => 'roles',
74 role_field => 'rolename',
75 ignore_fields_in_find => [ 'remote_name' ],
76 use_userdata_from_session => 1,
77 }
78 }
79 }
80 });
81
82 class
83 Class is part of the core Catalyst::Plugin::Authentication module;
84 it contains the class name of the store to be used.
85
86 user_model
87 Contains the model name (as passed to "$ctx->model()") of the
88 DBIx::Class schema to use as the source for user information. This
89 config item is REQUIRED.
90
91 (Note that this option used to be called "user_class". "user_class"
92 is still functional, but should be used only for compatibility with
93 previous configs. The setting called "user_class" on other
94 authentication stores is present, but named "store_user_class" in
95 this store)
96
97 role_column
98 If your role information is stored in the same table as the rest of
99 your user information, this item tells the module which field
100 contains your role information. The DBIx::Class authentication store
101 expects the data in this field to be a series of role names
102 separated by some combination of spaces, commas, or pipe characters.
103
104 role_relation
105 If your role information is stored in a separate table, this is the
106 name of the relation that will lead to the roles the user is in. If
107 this is specified, then a role_field is also required. Also when
108 using this method it is expected that your role table will return
109 one row for each role the user is in.
110
111 role_field
112 This is the name of the field in the role table that contains the
113 string identifying the role.
114
115 ignore_fields_in_find
116 This item is an array containing fields that may be passed to the
117 "$ctx->authenticate()" routine (and therefore find_user in the
118 storage class), but which should be ignored when creating the
119 DBIx::Class search to retrieve a user. This makes it possible to
120 avoid problems when a credential requires an authinfo element whose
121 name overlaps with a column name in your users table. If this
122 doesn't make sense to you, you probably don't need it.
123
124 use_userdata_from_session
125 Under normal circumstances, on each request the user's data is
126 re-retrieved from the database using the primary key for the user
127 table. When this flag is set in the configuration, it causes the
128 DBIx::Class store to avoid this database hit on session restore.
129 Instead, the user object's column data is retrieved from the session
130 and used as-is.
131
132 NOTE: Since the user object's column data is only stored in the
133 session during the initial authentication of the user, turning this
134 on can potentially lead to a situation where the data in
135 "$ctx->user" is different from what is stored the database. You can
136 force a reload of the data from the database at any time by calling
137 "$ctx->user->get_object(1);" Note that this will update "$ctx->user"
138 for the remainder of this request. It will NOT update the session.
139 If you need to update the session you should call
140 "$ctx->update_user_in_session()" as well.
141
142 store_user_class
143 This allows you to override the authentication user class that the
144 DBIx::Class store module uses to perform its work. Most of the work
145 done in this module is actually done by the user class,
146 Catalyst::Authentication::Store::DBIx::Class::User, so overriding
147 this doesn't make much sense unless you are using your own class to
148 extend the functionality of the existing class. Chances are you do
149 not want to set this.
150
151 id_field
152 In most cases, this config variable does not need to be set, as
153 Catalyst::Authentication::Store::DBIx::Class will determine the
154 primary key of the user table on its own. If you need to override
155 the default, or your user table has multiple primary keys, then
156 id_field should contain the column name that should be used to
157 restore the user. A given value in this column should correspond to
158 a single user in the database. Note that this is used ONLY when
159 restoring a user from the session and has no bearing whatsoever in
160 the initial authentication process. Note also that if
161 use_userdata_from_session is enabled, this config parameter is not
162 used at all.
163
164 USAGE
165 The Catalyst::Authentication::Store::DBIx::Class storage module is not
166 called directly from application code. You interface with it through the
167 $ctx->authenticate() call.
168
169 There are three methods you can use to retrieve information from the
170 DBIx::Class storage module. They are Simple retrieval, and the advanced
171 retrieval methods Searchargs and Resultset.
172
173 Simple Retrieval
174 The first, and most common, method is simple retrieval. As its name
175 implies simple retrieval allows you to simply to provide the column =>
176 value pairs that should be used to locate the user in question. An
177 example of this usage is below:
178
179 if ($ctx->authenticate({
180 screen_name => $ctx->req->params->{'username'},
181 password => $ctx->req->params->{'password'},
182 status => [ 'registered', 'active', 'loggedin']
183 })) {
184
185 # ... authenticated user code here
186 }
187
188 The above example would attempt to retrieve a user whose username column
189 (here, screen_name) matched the username provided, and whose status
190 column matched one of the values provided. These name => value pairs are
191 used more or less directly in the DBIx::Class search() routine, so in
192 most cases, you can use DBIx::Class syntax to retrieve the user
193 according to whatever rules you have.
194
195 NOTE: Because the password in most cases is encrypted - it is not used
196 directly but its encryption and comparison with the value provided is
197 usually handled by the Password Credential. Part of the Password
198 Credential's behavior is to remove the password argument from the
199 authinfo that is passed to the storage module. See
200 Catalyst::Authentication::Credential::Password.
201
202 One thing you need to know about this retrieval method is that the name
203 portion of the pair is checked against the user class's column list.
204 Pairs are only used if a matching column is found. Other pairs will be
205 ignored. This means that you can only provide simple name-value pairs,
206 and that some more advanced DBIx::Class constructs, such as '-or',
207 '-and', etc. are in most cases not possible using this method. For
208 queries that require this level of functionality, see the 'searchargs'
209 method below.
210
211 Advanced Retrieval
212 The Searchargs and Resultset retrieval methods are used when more
213 advanced features of the underlying DBIx::Class schema are required.
214 These methods provide a direct interface with the DBIx::Class schema and
215 therefore require a better understanding of the DBIx::Class module.
216
217 The dbix_class key
218 Since the format of these arguments are often complex, they are not keys
219 in the base authinfo hash. Instead, both of these arguments are placed
220 within a hash attached to the store-specific 'dbix_class' key in the
221 base $authinfo hash. When the DBIx::Class authentication store sees the
222 'dbix_class' key in the passed authinfo hash, all the other information
223 in the authinfo hash is ignored and only the values within the
224 'dbix_class' hash are used as though they were passed directly within
225 the authinfo hash. In other words, if 'dbix_class' is present, it
226 replaces the authinfo hash for processing purposes.
227
228 The 'dbix_class' hash can be used to directly pass arguments to the
229 DBIx::Class authentication store. Reasons to do this are to avoid
230 credential modification of the authinfo hash, or to avoid overlap
231 between credential and store key names. It's a good idea to avoid using
232 it in this way unless you are sure you have an overlap/modification
233 issue. However, the two advanced retrieval methods, searchargs, result
234 and resultset, require its use, as they are only processed as part of
235 the 'dbix_class' hash.
236
237 Searchargs
238 The searchargs method of retrieval allows you to specify an arrayref
239 containing the two arguments to the search() method from
240 DBIx::Class::ResultSet. If provided, all other args are ignored, and
241 the search args provided are used directly to locate the user. An
242 example will probably make more sense:
243
244 if ($ctx->authenticate(
245 {
246 password => $password,
247 'dbix_class' =>
248 {
249 searchargs => [ { -or => [ username => $username,
250 email => $email,
251 clientid => $clientid ]
252 },
253 { prefetch => qw/ preferences / }
254 ]
255 }
256 } ) )
257 {
258 # do successful authentication actions here.
259 }
260
261 The above would allow authentication based on any of the three items
262 - username, email, or clientid - and would prefetch the data related
263 to that user from the preferences table. The searchargs array is
264 passed directly to the search() method associated with the
265 user_model.
266
267 Result
268 The result method of retrieval allows you to look up the user
269 yourself and pass on the loaded user to the authentication store.
270
271 my $user = $ctx->model('MyApp::User')->find({ ... });
272
273 if ($ctx->authenticate({ dbix_class => { result => $user } })) {
274 ...
275 }
276
277 Be aware that the result method will not verify that you are passing
278 a result that is attached to the same user_model as specified in the
279 config or even loaded from the database, as opposed to existing only
280 in memory. It's your responsibility to make sure of that.
281
282 Resultset
283 The resultset method of retrieval allows you to directly specify a
284 resultset to be used for user retrieval. This allows you to create a
285 resultset within your login action and use it for retrieving the
286 user. A simple example:
287
288 my $rs = $ctx->model('MyApp::User')->search({ email => $ctx->request->params->{'email'} });
289 ... # further $rs adjustments
290
291 if ($ctx->authenticate({
292 password => $password,
293 'dbix_class' => { resultset => $rs }
294 })) {
295 # do successful authentication actions here.
296 }
297
298 Be aware that the resultset method will not verify that you are
299 passing a resultset that is attached to the same user_model as
300 specified in the config.
301
302 NOTE: The resultset and searchargs methods of user retrieval,
303 consider the first row returned to be the matching user. In most
304 cases there will be only one matching row, but it is easy to produce
305 multiple rows, especially when using the advanced retrieval methods.
306 Remember, what you get when you use this module is what you would
307 get when calling search(...)->first;
308
309 NOTE ALSO: The user info used to save the user to the session and to
310 retrieve it is the same regardless of what method of retrieval was
311 used. In short, the value in the id field (see 'id_field' config
312 item) is used to retrieve the user from the database upon restoring
313 from the session. When the DBIx::Class storage module does this, it
314 does so by doing a simple search using the id field. In other words,
315 it will not use the same arguments you used to request the user
316 initially. This is especially important to those using the advanced
317 methods of user retrieval. If you need more complicated logic when
318 reviving the user from the session, you will most likely want to
319 subclass the Catalyst::Authentication::Store::DBIx::Class::User
320 class and provide your own for_session and from_session routines.
321
322 METHODS
323 There are no publicly exported routines in the DBIx::Class
324 authentication store (or indeed in most authentication stores). However,
325 below is a description of the routines required by
326 Catalyst::Plugin::Authentication for all authentication stores. Please
327 see the documentation for Catalyst::Plugin::Authentication::Internals
328 for more information.
329
330 new ( $config, $app )
331 Constructs a new store object.
332
333 find_user ( $authinfo, $c )
334 Finds a user using the information provided in the $authinfo hashref and
335 returns the user, or undef on failure. This is usually called from the
336 Credential. This translates directly to a call to
337 Catalyst::Authentication::Store::DBIx::Class::User's load() method.
338
339 for_session ( $c, $user )
340 Prepares a user to be stored in the session. Currently returns the value
341 of the user's id field (as indicated by the 'id_field' config element)
342
343 from_session ( $c, $frozenuser)
344 Revives a user from the session based on the info provided in
345 $frozenuser. Currently treats $frozenuser as an id and retrieves a user
346 with a matching id.
347
348 user_supports
349 Provides information about what the user object supports.
350
351 auto_update_user( $authinfo, $c, $res )
352 This method is called if the realm's auto_update_user setting is true.
353 It will delegate to the user object's "auto_update" method.
354
355 auto_create_user( $authinfo, $c )
356 This method is called if the realm's auto_create_user setting is true.
357 It will delegate to the user class's (resultset) "auto_create" method.
358
359 NOTES
360 As of the current release, session storage consists of simply storing
361 the user's id in the session, and then using that same id to re-retrieve
362 the user's information from the database upon restoration from the
363 session. More dynamic storage of user information in the session is
364 intended for a future release.
365
366 BUGS AND LIMITATIONS
367 None known currently; please email the author if you find any.
368
369 SEE ALSO
370 Catalyst::Plugin::Authentication,
371 Catalyst::Plugin::Authentication::Internals, and
372 Catalyst::Plugin::Authorization::Roles
373
374 AUTHOR
375 Jason Kuri ([email protected])
376
377 LICENSE
378 Copyright (c) 2007 the aforementioned authors. All rights reserved. This
379 program is free software; you can redistribute it and/or modify it under
380 the same terms as Perl itself.
381