1Catalyst::Plugin::AutheUnsteircaCtoinotnr(i3b)uted PerlCDaotcaulmyesntt:a:tPiloungin::Authentication(3)
2
3
4

NAME

6       Catalyst::Plugin::Authentication - Infrastructure plugin for the
7       Catalyst authentication framework.
8

SYNOPSIS

10           use Catalyst qw/
11               Authentication
12           /;
13
14           # later on ...
15           $c->authenticate({ username => 'myusername',
16                              password => 'mypassword' });
17           my $age = $c->user->get('age');
18           $c->logout;
19

DESCRIPTION

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
26       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
34       To implement authentication in a Catalyst application you need to add
35       this module, and specify at least one realm in the configuration.
36
37       Authentication data can also be stored in a session, if the application
38       is using the Catalyst::Plugin::Session module.
39
40       NOTE in version 0.10 of this module, the interface to this module
41       changed.  Please see "COMPATIBILITY ROUTINES" for more information.
42

INTRODUCTION

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
51       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
55       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
62       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
66       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
75   The Components In This Framework
76       Realms
77
78       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
83       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
91       Credential Verifiers
92
93       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
98       These plugins check the data, and ensure that it really proves the user
99       is who they claim to be.
100
101       Credential verifiers compatible with versions of this module 0.10x and
102       upwards should be in the namespace
103       "Catalyst::Authentication::Credential".
104
105       Storage Backends
106
107       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
111       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
116       Storage backends compatible with versions of this module 0.10x and
117       upwards should be in the namespace "Catalyst::Authentication::Store".
118
119       The Core Plugin
120
121       This plugin on its own is the glue, providing realm configuration,
122       session integration, and other goodness for the other plugins.
123
124       Other Plugins
125
126       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

EXAMPLE

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
137       This means that our application will begin like this:
138
139           package MyApp;
140
141           use Catalyst qw/
142               Authentication
143           /;
144
145           __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
171       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
175       To show an example of this, let's create an authentication controller:
176
177           package MyApp::Controller::Auth;
178
179           sub login : Local {
180               my ( $self, $c ) = @_;
181
182               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
197       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
201       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
207       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
212           if ( $c->authenticate( { username => $user,
213                                    password => $password }, 'admin' ) ) {
214               $c->res->body( "hello " . $c->user->get("name") );
215           } ...
216
217       Now suppose we want to restrict the ability to edit to a user with an
218       'editor' value of yes.
219
220       The restricted action might look like this:
221
222           sub edit : Local {
223               my ( $self, $c ) = @_;
224
225               $c->detach("unauthorized")
226                 unless $c->user_exists
227                 and $c->user->get('editor') eq 'yes';
228
229               # do something restricted here
230           }
231
232       (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
238       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
243           use Catalyst qw/
244               ...
245               Authorization::Roles
246           /;
247
248           sub edit : Local {
249               my ( $self, $c ) = @_;
250
251               $c->detach("unauthorized") unless $c->check_user_roles("edit");
252
253               # do something restricted here
254           }
255
256       This is somewhat simpler and will work if you change your store, too,
257       since the role interface is consistent.
258
259       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
264           __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
282       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

CONFIGURATION

287           # example
288           __PACKAGE__->config( 'Plugin::Authentication' =>
289                       {
290                           default_realm => 'members',
291
292                           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
318       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
322       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
327           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
334       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
339       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
349           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
353           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
360           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

METHODS

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
375   $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
382   $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
390   $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
394   $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
398   $c->find_user( $userinfo, $realm )
399       Fetch a particular users details, matching the provided user info, from
400       the realm specified in $realm.
401
402           $user = $c->find_user({ id => $id });
403           $c->set_authenticated($user); # logs the user in and calls persist_user
404
405   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
413   find_realm_for_persisted_user()
414       Private method, do not call from user code!
415

INTERNAL METHODS

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
423   $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
428   $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
434   $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
439   $c->get_auth_realm( $realmname )
440       Retrieves the realm instance for the realmname provided.
441
442   $c->update_user_in_session
443       This was a short-lived method to update user information - you should
444       use persist_user instead.
445
446   $c->setup_auth_realm( )

OVERRIDDEN METHODS

448   $c->setup( )

SEE ALSO

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
453   Realms
454       Catalyst::Authentication::Realm
455
456   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
465   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
475   Authorization
476       Catalyst::Plugin::Authorization::ACL,
477       Catalyst::Plugin::Authorization::Roles
478
479   Internals Documentation
480       Catalyst::Plugin::Authentication::Internals
481
482   Misc
483       Catalyst::Plugin::Session, Catalyst::Plugin::Session::PerUser
484

DON'T SEE ALSO

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

INCOMPATABILITIES

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

COMPATIBILITY CONFIGURATION

503       Until version 0.10008 of this module, you needed to put all the realms
504       inside a "realms" key in the configuration.
505
506           # example
507           __PACKAGE__->config( 'Plugin::Authentication' =>
508                       {
509                           default_realm => 'members',
510                           realms => {
511                               members => {
512                                   ...
513                               },
514                           },
515                       }
516           );
517
518       If you use the old, deprecated "__PACKAGE__->config( 'authentication'
519       )" configuration key, then the realms key is still required.
520

COMPATIBILITY ROUTINES

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
526       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
530       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
536       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
540   $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
546   $c->default_auth_store( )
547       Return the store whose name is 'default'.
548
549       This is set to "$c->config( 'Plugin::Authentication' => { store => #
550       Store} )" if that value exists, or by using a Store plugin:
551
552           # load the Minimal authentication store.
553           use Catalyst qw/Authentication Authentication::Store::Minimal/;
554
555       Sets the default store to
556       Catalyst::Plugin::Authentication::Store::Minimal.
557
558   $c->get_auth_store( $name )
559       Return the store whose name is $name.
560
561   $c->get_auth_store_name( $store )
562       Return the name of the store $store.
563
564   $c->auth_stores( )
565       A hash keyed by name, with the stores registered in the app.
566
567   $c->register_auth_stores( %stores_by_name )
568       Register stores into the application.
569
570   $c->auth_store_names( )
571   $c->get_user( )

SUPPORT

573       Please use the rt.cpan.org bug tracker, and git patches are wecome.
574
575       Questions on usage should be directed to the Catalyst mailing list or
576       the #catalyst irc channel.
577

AUTHORS

579       Yuval Kogman, "nothingmuch@woobling.org" - original author
580
581       Jay Kuri, "jayk@cpan.org" - Large rewrite
582

PRIMARY MAINTAINER

584       Tomas Doran (t0m), "bobtfish@bobtfish.net"
585

ADDITIONAL CONTRIBUTORS

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
601       This program is free software; you can redistribute it and/or modify it
602       under the same terms as Perl itself.
603
604
605
606perl v5.36.0                      2023-01-20Catalyst::Plugin::Authentication(3)
Impressum