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 Normally the user is re-retrieved from the store. For
378 Catalyst::Authentication::Store::DBIx::Class the user is re-restored
379 using the primary key of the user table. Thus user can throw an error
380 even though user_exists returned true.
381 $c->user_exists( )
383 Returns true if a user is logged in right now. The difference between
384 user_exists and user is that user_exists will return true if a user is
385 logged in, even if it has not been yet retrieved from the storage
386 backend. If you only need to know if the user is logged in, depending
387 on the storage mechanism this can be much more efficient. user_exists
388 only looks into the session while user is trying to restore the user.
389 $c->user_in_realm( $realm )
391 Works like user_exists, except that it only returns true if a user is
392 both logged in right now and was retrieved from the realm provided.
393 $c->logout( )
395 Logs the user out. Deletes the currently logged in user from "$c->user"
396 and the session. It does not delete the session.
397 $c->find_user( $userinfo, $realm )
399 Fetch a particular users details, matching the provided user info, from
400 the realm specified in $realm.
401 $user = $c->find_user({ id => $id });
403 $c->set_authenticated($user); # logs the user in and calls persist_user
404 persist_user()
406 Under normal circumstances the user data is only saved to the session
407 during initial authentication. This call causes the auth system to
408 save the currently authenticated user's data across requests. Useful
409 if you have changed the user data and want to ensure that future
410 requests reflect the most current data. Assumes that at the time of
411 this call, $c->user contains the most current data.
412 find_realm_for_persisted_user()
414 Private method, do not call from user code!
415
417 These methods are for Catalyst::Plugin::Authentication INTERNAL USE
418 only. Please do not use them in your own code, whether application or
419 credential / store modules. If you do, you will very likely get the
420 nasty shock of having to fix / rewrite your code when things change.
421 They are documented here only for reference.
422 $c->set_authenticated( $user, $realmname )
424 Marks a user as authenticated. This is called from within the
425 authenticate routine when a credential returns a user. $realmname
426 defaults to 'default'. You can use find_user to get $user
427 $c->auth_restore_user( $user, $realmname )
429 Used to restore a user from the session. In most cases this is called
430 without arguments to restore the user via the session. Can be called
431 with arguments when restoring a user from some other method. Currently
432 not used in this way.
433 $c->auth_realms( )
435 Returns a hashref containing realmname -> realm instance pairs. Realm
436 instances contain an instantiated store and credential object as the
437 'store' and 'credential' elements, respectively
438 $c->get_auth_realm( $realmname )
440 Retrieves the realm instance for the realmname provided.
441 $c->update_user_in_session
443 This was a short-lived method to update user information - you should
444 use persist_user instead.
445 $c->setup_auth_realm( )
448 $c->setup( )
450 This list might not be up to date. Below are modules known to work
451 with the updated API of 0.10 and are therefore compatible with realms.
452 Realms
454 Catalyst::Authentication::Realm
455 User Storage Backends
457 Catalyst::Authentication::Store::Minimal
458 Catalyst::Authentication::Store::DBIx::Class
459 Catalyst::Authentication::Store::LDAP
460 Catalyst::Authentication::Store::RDBO
461 Catalyst::Authentication::Store::Model::KiokuDB
462 Catalyst::Authentication::Store::Jifty::DBI
463 Catalyst::Authentication::Store::Htpasswd
464 Credential verification
466 Catalyst::Authentication::Credential::Password
467 Catalyst::Authentication::Credential::HTTP
468 Catalyst::Authentication::Credential::OpenID
469 Catalyst::Authentication::Credential::Authen::Simple
470 Catalyst::Authentication::Credential::Flickr
471 Catalyst::Authentication::Credential::Testing
472 Catalyst::Authentication::Credential::AuthTkt
473 Catalyst::Authentication::Credential::Kerberos
474 Authorization
476 Catalyst::Plugin::Authorization::ACL,
477 Catalyst::Plugin::Authorization::Roles
478 Internals Documentation
480 Catalyst::Plugin::Authentication::Internals
481 Misc
483 Catalyst::Plugin::Session, Catalyst::Plugin::Session::PerUser
484
486 This module along with its sub plugins deprecate a great number of
487 other modules. These include Catalyst::Plugin::Authentication::Simple,
488 Catalyst::Plugin::Authentication::CDBI.
489
491 The realms-based configuration and functionality of the 0.10 update of
492 Catalyst::Plugin::Authentication required a change in the API used by
493 credentials and stores. It has a compatibility mode which allows use
494 of modules that have not yet been updated. This, however, completely
495 mimics the older api and disables the new realm-based features. In
496 other words you cannot mix the older credential and store modules with
497 realms, or realm-based configs. The changes required to update modules
498 are relatively minor and are covered in
499 Catalyst::Plugin::Authentication::Internals. We hope that most modules
500 will move to the compatible list above very quickly.
501
503 Until version 0.10008 of this module, you needed to put all the realms
504 inside a "realms" key in the configuration.
505 # example
507 __PACKAGE__->config( 'Plugin::Authentication' =>
508 {
509 default_realm => 'members',
510 realms => {
511 members => {
512 ...
513 },
514 },
515 }
516 );
517 If you use the old, deprecated "__PACKAGE__->config( 'authentication'
519 )" configuration key, then the realms key is still required.
520
522 In version 0.10 of Catalyst::Plugin::Authentication, the API changed.
523 For app developers, this change is fairly minor, but for Credential and
524 Store authors, the changes are significant.
525 Please see the documentation in version 0.09 of
527 Catalyst::Plugin::Authentication for a better understanding of how the
528 old API functioned.
529 The items below are still present in the plugin, though using them is
531 deprecated. They remain only as a transition tool, for those sites
532 which can not yet be upgraded to use the new system due to local
533 customizations or use of Credential / Store modules that have not yet
534 been updated to work with the new API.
535 These routines should not be used in any application using realms
537 functionality or any of the methods described above. These are for
538 reference purposes only.
539 $c->login( )
541 This method is used to initiate authentication and user retrieval.
542 Technically this is part of the old Password credential module and it
543 still resides in the Password class. It is included here for reference
544 only.
545 $c->default_auth_store( )
547 Return the store whose name is 'default'.
548 This is set to "$c->config( 'Plugin::Authentication' => { store => #
550 Store} )" if that value exists, or by using a Store plugin:
551 # load the Minimal authentication store.
553 use Catalyst qw/Authentication Authentication::Store::Minimal/;
554 Sets the default store to
556 Catalyst::Plugin::Authentication::Store::Minimal.
557 $c->get_auth_store( $name )
559 Return the store whose name is $name.
560 $c->get_auth_store_name( $store )
562 Return the name of the store $store.
563 $c->auth_stores( )
565 A hash keyed by name, with the stores registered in the app.
566 $c->register_auth_stores( %stores_by_name )
568 Register stores into the application.
569 $c->auth_store_names( )
571 $c->get_user( )
573 Please use the rt.cpan.org bug tracker, and git patches are wecome.
574 Questions on usage should be directed to the Catalyst mailing list or
576 the #catalyst irc channel.
577
579 Yuval Kogman, "nothingmuch@woobling.org" - original author
580 Jay Kuri, "jayk@cpan.org" - Large rewrite
582
584 Tomas Doran (t0m), "bobtfish@bobtfish.net"
585
587 Jess Robinson
588 David Kamholz
589 kmx
590 Nigel Metheringham
591 Florian Ragwitz "rafl@debian.org"
592 Stephan Jauernick "stephanj@cpan.org"
593 Oskari Ojala (Okko), "perl@okko.net"
594 John Napiorkowski (jnap) "jjnapiork@cpan.org"
595
597 Copyright (c) 2005 - 2012 the Catalyst::Plugin::Authentication
598 "AUTHORS", "PRIMARY MAINTAINER" and "ADDITIONAL CONTRIBUTORS" as listed
599 above.
600 This program is free software; you can redistribute it and/or modify it
602 under the same terms as Perl itself.
603perl v5.36.0 2023-01-20Catalyst::Plugin::Authentication(3)