1Catalyst::Plugin::AutheUnsteircaCtoinotnr(i3b)uted PerlCDaotcaulmyesntt:a:tPiloungin::Authentication(3)
2
6 Catalyst::Plugin::Authentication - Infrastructure plugin for the
7 Catalyst authentication framework.
8
10 use Catalyst qw/
11 Authentication
12 /;
13 # later on ...
15 $c->authenticate({ username => 'myusername',
16 password => 'mypassword' });
17 my $age = $c->user->get('age');
18 $c->logout;
19
21 The authentication plugin provides generic user support for Catalyst
22 apps. It is the basis for both authentication (checking the user is who
23 they claim to be), and authorization (allowing the user to do what the
24 system authorises them to do).
25 Using authentication is split into two parts. A Store is used to
27 actually store the user information, and can store any amount of data
28 related to the user. Credentials are used to verify users, using
29 information from the store, given data from the frontend. A Credential
30 and a Store are paired to form a 'Realm'. A Catalyst application using
31 the authentication framework must have at least one realm, and may have
32 several.
33 To implement authentication in a Catalyst application you need to add
35 this module, and specify at least one realm in the configuration.
36 Authentication data can also be stored in a session, if the application
38 is using the Catalyst::Plugin::Session module.
39 NOTE in version 0.10 of this module, the interface to this module
41 changed. Please see "COMPATIBILITY ROUTINES" for more information.
42
44 The Authentication/Authorization Process
45 Web applications typically need to identify a user - to tell the user
46 apart from other users. This is usually done in order to display
47 private information that is only that user's business, or to limit
48 access to the application so that only certain entities can access
49 certain parts.
50 This process is split up into several steps. First you ask the user to
52 identify themselves. At this point you can't be sure that the user is
53 really who they claim to be.
54 Then the user tells you who they are, and backs this claim with some
56 piece of information that only the real user could give you. For
57 example, a password is a secret that is known to both the user and you.
58 When the user tells you this password you can assume they're in on the
59 secret and can be trusted (ignore identity theft for now). Checking the
60 password, or any other proof is called credential verification.
61 By this time you know exactly who the user is - the user's identity is
63 authenticated. This is where this module's job stops, and your
64 application or other plugins step in.
65 The next logical step is authorization, the process of deciding what a
67 user is (or isn't) allowed to do. For example, say your users are split
68 into two main groups - regular users and administrators. You want to
69 verify that the currently logged in user is indeed an administrator
70 before performing the actions in an administrative part of your
71 application. These decisions may be made within your application code
72 using just the information available after authentication, or it may be
73 facilitated by a number of plugins.
74 The Components In This Framework
76 Realms
77 Configuration of the Catalyst::Plugin::Authentication framework is done
79 in terms of realms. In simplest terms, a realm is a pairing of a
80 Credential verifier and a User storage (Store) backend. As of version
81 0.10003, realms are now objects that you can create and customize.
82 An application can have any number of Realms, each of which operates
84 independent of the others. Each realm has a name, which is used to
85 identify it as the target of an authentication request. This name can
86 be anything, such as 'users' or 'members'. One realm must be defined as
87 the default_realm, which is used when no realm name is specified. More
88 information about configuring realms is available in the configuration
89 section.
90 Credential Verifiers
92 When user input is transferred to the Catalyst application (typically
94 via form inputs) the application may pass this information into the
95 authentication system through the "$c->authenticate()" method. From
96 there, it is passed to the appropriate Credential verifier.
97 These plugins check the data, and ensure that it really proves the user
99 is who they claim to be.
100 Credential verifiers compatible with versions of this module 0.10x and
102 upwards should be in the namespace
103 "Catalyst::Authentication::Credential".
104 Storage Backends
106 The authentication data also identifies a user, and the Storage backend
108 modules use this data to locate and return a standardized object-
109 oriented representation of a user.
110 When a user is retrieved from a store it is not necessarily
112 authenticated. Credential verifiers accept a set of authentication
113 data and use this information to retrieve the user from the store they
114 are paired with.
115 Storage backends compatible with versions of this module 0.10x and
117 upwards should be in the namespace "Catalyst::Authentication::Store".
118 The Core Plugin
120 This plugin on its own is the glue, providing realm configuration,
122 session integration, and other goodness for the other plugins.
123 Other Plugins
125 More layers of plugins can be stacked on top of the authentication
127 code. For example, Catalyst::Plugin::Session::PerUser provides an
128 abstraction of browser sessions that is more persistent per user.
129 Catalyst::Plugin::Authorization::Roles provides an accepted way to
130 separate and group users into categories, and then check which
131 categories the current user belongs to.
132
134 Let's say we were storing users in a simple Perl hash. Users are
135 verified by supplying a password which is matched within the hash.
136 This means that our application will begin like this:
138 package MyApp;
140 use Catalyst qw/
142 Authentication
143 /;
144 __PACKAGE__->config( 'Plugin::Authentication' =>
146 {
147 default => {
148 credential => {
149 class => 'Password',
150 password_field => 'password',
151 password_type => 'clear'
152 },
153 store => {
154 class => 'Minimal',
155 users => {
156 bob => {
157 password => "s00p3r",
158 editor => 'yes',
159 roles => [qw/edit delete/],
160 },
161 william => {
162 password => "s3cr3t",
163 roles => [qw/comment/],
164 }
165 }
166 }
167 }
168 }
169 );
170 This tells the authentication plugin what realms are available, which
172 credential and store modules are used, and the configuration of each.
173 With this code loaded, we can now attempt to authenticate users.
174 To show an example of this, let's create an authentication controller:
176 package MyApp::Controller::Auth;
178 sub login : Local {
180 my ( $self, $c ) = @_;
181 if ( my $user = $c->req->params->{user}
183 and my $password = $c->req->params->{password} )
184 {
185 if ( $c->authenticate( { username => $user,
186 password => $password } ) ) {
187 $c->res->body( "hello " . $c->user->get("name") );
188 } else {
189 # login incorrect
190 }
191 }
192 else {
193 # invalid form input
194 }
195 }
196 This code should be self-explanatory. If all the necessary fields are
198 supplied, call the "authenticate" method on the context object. If it
199 succeeds the user is logged in.
200 The credential verifier will attempt to retrieve the user whose details
202 match the authentication information provided to "$c->authenticate()".
203 Once it fetches the user the password is checked and if it matches the
204 user will be authenticated and "$c->user" will contain the user object
205 retrieved from the store.
206 In the above case, the default realm is checked, but we could just as
208 easily check an alternate realm. If this were an admin login, for
209 example, we could authenticate on the admin realm by simply changing
210 the "$c->authenticate()" call:
211 if ( $c->authenticate( { username => $user,
213 password => $password }, 'admin' ) ) {
214 $c->res->body( "hello " . $c->user->get("name") );
215 } ...
216 Now suppose we want to restrict the ability to edit to a user with an
218 'editor' value of yes.
219 The restricted action might look like this:
221 sub edit : Local {
223 my ( $self, $c ) = @_;
224 $c->detach("unauthorized")
226 unless $c->user_exists
227 and $c->user->get('editor') eq 'yes';
228 # do something restricted here
230 }
231 (Note that if you have multiple realms, you can use
233 "$c->user_in_realm('realmname')" in place of "$c->user_exists();" This
234 will essentially perform the same verification as user_exists, with the
235 added requirement that if there is a user, it must have come from the
236 realm specified.)
237 The above example is somewhat similar to role based access control.
239 Catalyst::Authentication::Store::Minimal treats the roles field as an
240 array of role names. Let's leverage this. Add the role authorization
241 plugin:
242 use Catalyst qw/
244 ...
245 Authorization::Roles
246 /;
247 sub edit : Local {
249 my ( $self, $c ) = @_;
250 $c->detach("unauthorized") unless $c->check_user_roles("edit");
252 # do something restricted here
254 }
255 This is somewhat simpler and will work if you change your store, too,
257 since the role interface is consistent.
258 Let's say your app grows, and you now have 10,000 users. It's no longer
260 efficient to maintain a hash of users, so you move this data to a
261 database. You can accomplish this simply by installing the DBIx::Class
262 Store and changing your config:
263 __PACKAGE__->config( 'Plugin::Authentication' =>
265 {
266 default_realm => 'members',
267 members => {
268 credential => {
269 class => 'Password',
270 password_field => 'password',
271 password_type => 'clear'
272 },
273 store => {
274 class => 'DBIx::Class',
275 user_model => 'MyApp::Users',
276 role_column => 'roles',
277 }
278 }
279 }
280 );
281 The authentication system works behind the scenes to load your data
283 from the new source. The rest of your application is completely
284 unchanged.
285
287 # example
288 __PACKAGE__->config( 'Plugin::Authentication' =>
289 {
290 default_realm => 'members',
291 members => {
293 credential => {
294 class => 'Password',
295 password_field => 'password',
296 password_type => 'clear'
297 },
298 store => {
299 class => 'DBIx::Class',
300 user_model => 'MyApp::Users',
301 role_column => 'roles',
302 }
303 },
304 admins => {
305 credential => {
306 class => 'Password',
307 password_field => 'password',
308 password_type => 'clear'
309 },
310 store => {
311 class => '+MyApp::Authentication::Store::NetAuth',
312 authserver => '192.168.10.17'
313 }
314 }
315 }
316 );
317 NOTE: Until version 0.10008 of this module, you would need to put all
319 the realms inside a "realms" key in the configuration. Please see
320 "COMPATIBILITY CONFIGURATION" for more information
321 use_session
323 Whether or not to store the user's logged in state in the session,
324 if the application is also using Catalyst::Plugin::Session. This
325 value is set to true per default.
326 However, even if use_session is disabled, if any code touches
328 $c->session, a session object will be auto-vivified and session
329 Cookies will be sent in the headers. To prevent accidental session
330 creation, check if a session already exists with if ($c->sessionid)
331 { ... }. If the session doesn't exist, then don't place anything in
332 the session to prevent an unecessary session from being created.
333 default_realm
335 This defines which realm should be used as when no realm is
336 provided to methods that require a realm such as authenticate or
337 find_user.
338 realm refs
340 The Plugin::Authentication config hash contains the series of realm
341 configurations you want to use for your app. The only rule here is
342 that there must be at least one. A realm consists of a name, which
343 is used to reference the realm, a credential and a store. You may
344 also put your realm configurations within a subelement called
345 'realms' if you desire to separate them from the remainder of your
346 configuration. Note that if you use a 'realms' subelement, you
347 must put ALL of your realms within it.
348 You can also specify a realm class to instantiate instead of the
350 default Catalyst::Authentication::Realm class using the 'class'
351 element within the realm config.
352 Each realm config contains two hashes, one called 'credential' and
354 one called 'store', each of which provide configuration details to
355 the respective modules. The contents of these hashes is specific
356 to the module being used, with the exception of the 'class'
357 element, which tells the core Authentication module the classname
358 to instantiate.
359 The 'class' element follows the standard Catalyst mechanism of
361 class specification. If a class is prefixed with a +, it is assumed
362 to be a complete class name. Otherwise it is considered to be a
363 portion of the class name. For credentials, the classname
364 'Password', for example, is expanded to
365 Catalyst::Authentication::Credential::Password. For stores, the
366 classname 'storename' is expanded to:
367 Catalyst::Authentication::Store::storename.
368
370 $c->authenticate( $userinfo [, $realm ])
371 Attempts to authenticate the user using the information in the
372 $userinfo hash reference using the realm $realm. $realm may be omitted,
373 in which case the default realm is checked.
374 $c->user( )
376 Returns the currently logged in user, or undef if there is none.
377 $c->user_exists( )
379 Returns true if a user is logged in right now. The difference between
380 user_exists and user is that user_exists will return true if a user is
381 logged in, even if it has not been yet retrieved from the storage
382 backend. If you only need to know if the user is logged in, depending
383 on the storage mechanism this can be much more efficient.
384 $c->user_in_realm( $realm )
386 Works like user_exists, except that it only returns true if a user is
387 both logged in right now and was retrieved from the realm provided.
388 $c->logout( )
390 Logs the user out. Deletes the currently logged in user from "$c->user"
391 and the session. It does not delete the session.
392 $c->find_user( $userinfo, $realm )
394 Fetch a particular users details, matching the provided user info, from
395 the realm specified in $realm.
396 persist_user()
398 Under normal circumstances the user data is only saved to the session
399 during initial authentication. This call causes the auth system to
400 save the currently authenticated user's data across requests. Useful
401 if you have changed the user data and want to ensure that future
402 requests reflect the most current data. Assumes that at the time of
403 this call, $c->user contains the most current data.
404 find_realm_for_persisted_user()
406 Private method, do not call from user code!
407
409 These methods are for Catalyst::Plugin::Authentication INTERNAL USE
410 only. Please do not use them in your own code, whether application or
411 credential / store modules. If you do, you will very likely get the
412 nasty shock of having to fix / rewrite your code when things change.
413 They are documented here only for reference.
414 $c->set_authenticated( $user, $realmname )
416 Marks a user as authenticated. This is called from within the
417 authenticate routine when a credential returns a user. $realmname
418 defaults to 'default'
419 $c->auth_restore_user( $user, $realmname )
421 Used to restore a user from the session. In most cases this is called
422 without arguments to restore the user via the session. Can be called
423 with arguments when restoring a user from some other method. Currently
424 not used in this way.
425 $c->auth_realms( )
427 Returns a hashref containing realmname -> realm instance pairs. Realm
428 instances contain an instantiated store and credential object as the
429 'store' and 'credential' elements, respectively
430 $c->get_auth_realm( $realmname )
432 Retrieves the realm instance for the realmname provided.
433 $c->update_user_in_session
435 This was a short-lived method to update user information - you should
436 use persist_user instead.
437 $c->setup_auth_realm( )
440 $c->setup( )
442 This list might not be up to date. Below are modules known to work
443 with the updated API of 0.10 and are therefore compatible with realms.
444 Realms
446 Catalyst::Authentication::Realm
447 User Storage Backends
449 Catalyst::Authentication::Store::Minimal
450 Catalyst::Authentication::Store::DBIx::Class
451 Catalyst::Authentication::Store::LDAP
452 Catalyst::Authentication::Store::RDBO
453 Catalyst::Authentication::Store::Model::KiokuDB
454 Catalyst::Authentication::Store::Jifty::DBI
455 Catalyst::Authentication::Store::Htpasswd
456 Credential verification
458 Catalyst::Authentication::Credential::Password
459 Catalyst::Authentication::Credential::HTTP
460 Catalyst::Authentication::Credential::OpenID
461 Catalyst::Authentication::Credential::Authen::Simple
462 Catalyst::Authentication::Credential::Flickr
463 Catalyst::Authentication::Credential::Testing
464 Catalyst::Authentication::Credential::AuthTkt
465 Catalyst::Authentication::Credential::Kerberos
466 Authorization
468 Catalyst::Plugin::Authorization::ACL,
469 Catalyst::Plugin::Authorization::Roles
470 Internals Documentation
472 Catalyst::Plugin::Authentication::Internals
473 Misc
475 Catalyst::Plugin::Session, Catalyst::Plugin::Session::PerUser
476
478 This module along with its sub plugins deprecate a great number of
479 other modules. These include Catalyst::Plugin::Authentication::Simple,
480 Catalyst::Plugin::Authentication::CDBI.
481
483 The realms-based configuration and functionality of the 0.10 update of
484 Catalyst::Plugin::Authentication required a change in the API used by
485 credentials and stores. It has a compatibility mode which allows use
486 of modules that have not yet been updated. This, however, completely
487 mimics the older api and disables the new realm-based features. In
488 other words you cannot mix the older credential and store modules with
489 realms, or realm-based configs. The changes required to update modules
490 are relatively minor and are covered in
491 Catalyst::Plugin::Authentication::Internals. We hope that most modules
492 will move to the compatible list above very quickly.
493
495 Until version 0.10008 of this module, you needed to put all the realms
496 inside a "realms" key in the configuration.
497 # example
499 __PACKAGE__->config( 'Plugin::Authentication' =>
500 {
501 default_realm => 'members',
502 realms => {
503 members => {
504 ...
505 },
506 },
507 }
508 );
509 If you use the old, deprecated "__PACKAGE__->config( 'authentication'
511 )" configuration key, then the realms key is still required.
512
514 In version 0.10 of Catalyst::Plugin::Authentication, the API changed.
515 For app developers, this change is fairly minor, but for Credential and
516 Store authors, the changes are significant.
517 Please see the documentation in version 0.09 of
519 Catalyst::Plugin::Authentication for a better understanding of how the
520 old API functioned.
521 The items below are still present in the plugin, though using them is
523 deprecated. They remain only as a transition tool, for those sites
524 which can not yet be upgraded to use the new system due to local
525 customizations or use of Credential / Store modules that have not yet
526 been updated to work with the new API.
527 These routines should not be used in any application using realms
529 functionality or any of the methods described above. These are for
530 reference purposes only.
531 $c->login( )
533 This method is used to initiate authentication and user retrieval.
534 Technically this is part of the old Password credential module and it
535 still resides in the Password class. It is included here for reference
536 only.
537 $c->default_auth_store( )
539 Return the store whose name is 'default'.
540 This is set to "$c->config( 'Plugin::Authentication' => { store => #
542 Store} )" if that value exists, or by using a Store plugin:
543 # load the Minimal authentication store.
545 use Catalyst qw/Authentication Authentication::Store::Minimal/;
546 Sets the default store to
548 Catalyst::Plugin::Authentication::Store::Minimal.
549 $c->get_auth_store( $name )
551 Return the store whose name is $name.
552 $c->get_auth_store_name( $store )
554 Return the name of the store $store.
555 $c->auth_stores( )
557 A hash keyed by name, with the stores registered in the app.
558 $c->register_auth_stores( %stores_by_name )
560 Register stores into the application.
561 $c->auth_store_names( )
563 $c->get_user( )
565 Yuval Kogman, "nothingmuch@woobling.org"
566 Jay Kuri, "jayk@cpan.org"
568 Jess Robinson
570 David Kamholz
572 Tomas Doran (t0m), "bobtfish@bobtfish.net"
574 kmx
576 Nigel Metheringham
578 Florian Ragwitz "rafl@debian.org"
580 Stephan Jauernick "stephanj@cpan.org"
582
584 Copyright (c) 2005 - 2009 the Catalyst::Plugin::Authentication
585 "AUTHORS" as listed above.
586 This program is free software; you can redistribute it and/or modify it
588 under the same terms as Perl itself.
589perl v5.12.0 2010-01-22Catalyst::Plugin::Authentication(3)