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