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