3 package Catalyst::Plugin::Authentication;
5 use base qw/Class::Accessor::Fast Class::Data::Inheritable/;
8 __PACKAGE__->mk_accessors(qw/_user/);
9 __PACKAGE__->mk_classdata($_) for qw/_auth_realms/;
18 # this optimization breaks under Template::Toolkit
19 # use user_exists instead
22 # constant->import(have_want => eval { require Want });
25 our $VERSION = "0.10";
27 sub set_authenticated {
28 my ( $c, $user, $realmname ) = @_;
31 $c->request->{user} = $user; # compatibility kludge
34 $realmname = 'default';
37 if ( $c->isa("Catalyst::Plugin::Session")
38 and $c->config->{authentication}{use_session}
39 and $user->supports("session") )
41 $c->save_user_in_session($user, $realmname);
43 $user->auth_realm($realmname);
45 $c->NEXT::set_authenticated($user, $realmname);
48 sub _should_save_user_in_session {
49 my ( $c, $user ) = @_;
51 $c->_auth_sessions_supported
52 and $c->config->{authentication}{use_session}
53 and $user->supports("session");
56 sub _should_load_user_from_session {
57 my ( $c, $user ) = @_;
59 $c->_auth_sessions_supported
60 and $c->config->{authentication}{use_session}
61 and $c->session_is_valid;
64 sub _auth_sessions_supported {
66 $c->isa("Catalyst::Plugin::Session");
76 if ( defined($c->_user) ) {
79 return $c->auth_restore_user;
83 # change this to allow specification of a realm - to verify the user is part of that realm
84 # in addition to verifying that they exist.
87 return defined($c->_user) || defined($c->_user_in_session);
90 # works like user_exists - except only returns true if user
91 # exists AND is in the realm requested.
93 my ($c, $realmname) = @_;
95 if (defined($c->_user)) {
96 return ($c->_user->auth_realm eq $realmname);
97 } elsif (defined($c->_user_in_session)) {
98 return ($c->session->{__user_realm} eq $realmname);
104 sub save_user_in_session {
105 my ( $c, $user, $realmname ) = @_;
107 $c->session->{__user_realm} = $realmname;
109 # we want to ask the store for a user prepared for the session.
110 # but older modules split this functionality between the user and the
111 # store. We try the store first. If not, we use the old method.
112 my $realm = $c->get_auth_realm($realmname);
113 if ($realm->{'store'}->can('for_session')) {
114 $c->session->{__user} = $realm->{'store'}->for_session($c, $user);
116 $c->session->{__user} = $user->for_session;
126 $c->isa("Catalyst::Plugin::Session")
127 and $c->config->{authentication}{use_session}
128 and $c->session_is_valid
130 delete @{ $c->session }{qw/__user __user_realm/};
133 $c->NEXT::logout(@_);
137 my ( $c, $userinfo, $realmname ) = @_;
139 $realmname ||= 'default';
140 my $realm = $c->get_auth_realm($realmname);
141 if ( $realm->{'store'} ) {
142 return $realm->{'store'}->find_user($userinfo, $c);
144 $c->log->debug('find_user: unable to locate a store matching the requested realm');
149 sub _user_in_session {
152 return unless $c->_should_load_user_from_session;
154 return $c->session->{__user};
157 sub auth_restore_user {
158 my ( $c, $frozen_user, $realmname ) = @_;
160 $frozen_user ||= $c->_user_in_session;
161 return unless defined($frozen_user);
163 $realmname ||= $c->session->{__user_realm};
164 return unless $realmname; # FIXME die unless? This is an internal inconsistency
166 my $realm = $c->get_auth_realm($realmname);
167 $c->_user( my $user = $realm->{'store'}->from_session( $c, $frozen_user ) );
169 # this sets the realm the user originated in.
170 $user->auth_realm($realmname);
175 # we can't actually do our setup in setup because the model has not yet been loaded.
176 # So we have to trigger off of setup_finished. :-(
180 $c->_authentication_initialize();
184 ## the actual initialization routine. whee.
185 sub _authentication_initialize {
188 if ($c->_auth_realms) { return };
190 my $cfg = $c->config->{'authentication'} || {};
198 $c->_auth_realms($realmhash);
200 ## BACKWARDS COMPATIBILITY - if realm is not defined - then we are probably dealing
201 ## with an old-school config. The only caveat here is that we must add a classname
202 if (exists($cfg->{'realms'})) {
204 foreach my $realm (keys %{$cfg->{'realms'}}) {
205 $c->setup_auth_realm($realm, $cfg->{'realms'}{$realm});
208 # if we have a 'default-realm' in the config hash and we don't already
209 # have a realm called 'default', we point default at the realm specified
210 if (exists($cfg->{'default_realm'}) && !$c->get_auth_realm('default')) {
211 $c->_set_default_auth_realm($cfg->{'default_realm'});
214 foreach my $storename (keys %{$cfg->{'stores'}}) {
216 store => $cfg->{'stores'}{$storename},
218 $c->setup_auth_realm($storename, $realmcfg);
225 sub setup_auth_realm {
226 my ($app, $realmname, $config) = @_;
228 $app->log->debug("Setting up $realmname");
229 if (!exists($config->{'store'}{'class'})) {
230 Carp::croak "Couldn't setup the authentication realm named '$realmname', no class defined";
234 my $storeclass = $config->{'store'}{'class'};
236 ## follow catalyst class naming - a + prefix means a fully qualified class, otherwise it's
237 ## taken to mean C::P::A::Store::(specifiedclass)
238 if ($storeclass !~ /^\+(.*)$/ ) {
239 $storeclass = "Catalyst::Plugin::Authentication::Store::${storeclass}";
245 # a little niceness - since most systems seem to use the password credential class,
246 # if no credential class is specified we use password.
247 $config->{credential}{class} ||= "Catalyst::Plugin::Authentication::Credential::Password";
249 my $credentialclass = $config->{'credential'}{'class'};
251 ## follow catalyst class naming - a + prefix means a fully qualified class, otherwise it's
252 ## taken to mean C::P::A::Credential::(specifiedclass)
253 if ($credentialclass !~ /^\+(.*)$/ ) {
254 $credentialclass = "Catalyst::Plugin::Authentication::Credential::${credentialclass}";
256 $credentialclass = $1;
259 # if we made it here - we have what we need to load the classes;
260 Catalyst::Utils::ensure_class_loaded( $credentialclass );
261 Catalyst::Utils::ensure_class_loaded( $storeclass );
263 # BACKWARDS COMPATIBILITY - if the store class does not define find_user, we define it in terms
264 # of get_user and add it to the class. this is because the auth routines use find_user,
265 # and rely on it being present. (this avoids per-call checks)
266 if (!$storeclass->can('find_user')) {
268 *{"${storeclass}::find_user"} = sub {
269 my ($self, $info) = @_;
270 my @rest = @{$info->{rest}} if exists($info->{rest});
271 $self->get_user($info->{id}, @rest);
275 $app->auth_realms->{$realmname}{'store'} = $storeclass->new($config->{'store'}, $app);
276 $app->auth_realms->{$realmname}{'credential'} = $credentialclass->new($config->{'credential'}, $app);
282 return($self->_auth_realms);
286 my ($app, $realmname) = @_;
287 return $app->auth_realms->{$realmname};
291 # Very internal method. Vital Valuable Urgent, Do not touch on pain of death.
292 # Using this method just assigns the default realm to be the value associated
293 # with the realmname provided. It WILL overwrite any real realm called 'default'
294 # so can be very confusing if used improperly. It's used properly already.
295 # Translation: don't use it.
296 sub _set_default_auth_realm {
297 my ($app, $realmname) = @_;
299 if (exists($app->auth_realms->{$realmname})) {
300 $app->auth_realms->{'default'} = $app->auth_realms->{$realmname};
302 return $app->get_auth_realm('default');
306 my ($app, $userinfo, $realmname) = @_;
309 $realmname = 'default';
312 my $realm = $app->get_auth_realm($realmname);
314 ## note to self - make authenticate throw an exception if realm is invalid.
316 if ($realm && exists($realm->{'credential'})) {
317 my $user = $realm->{'credential'}->authenticate($app, $realm->{store}, $userinfo);
319 $app->set_authenticated($user, $realmname);
323 $app->log->debug("The realm requested, '$realmname' does not exist," .
324 " or there is no credential associated with it.")
329 ## BACKWARDS COMPATIBILITY -- Warning: Here be monsters!
331 # What follows are backwards compatibility routines - for use with Stores and Credentials
332 # that have not been updated to work with C::P::Authentication v0.10.
333 # These are here so as to not break people's existing installations, but will go away
334 # in a future version.
336 # The old style of configuration only supports a single store, as each store module
337 # sets itself as the default store upon being loaded. This is the only supported
338 # 'compatibility' mode.
342 my ( $c, $uid, @rest ) = @_;
344 return $c->find_user( {'id' => $uid, 'rest'=>\@rest }, 'default' );
348 ## this should only be called when using old-style authentication plugins. IF this gets
349 ## called in a new-style config - it will OVERWRITE the store of your default realm. Don't do it.
350 ## also - this is a partial setup - because no credential is instantiated... in other words it ONLY
351 ## works with old-style auth plugins and C::P::Authentication in compatibility mode. Trying to combine
352 ## this with a realm-type config will probably crash your app.
353 sub default_auth_store {
356 if ( my $new = shift ) {
357 $self->auth_realms->{'default'}{'store'} = $new;
358 my $storeclass = ref($new);
360 # BACKWARDS COMPATIBILITY - if the store class does not define find_user, we define it in terms
361 # of get_user and add it to the class. this is because the auth routines use find_user,
362 # and rely on it being present. (this avoids per-call checks)
363 if (!$storeclass->can('find_user')) {
365 *{"${storeclass}::find_user"} = sub {
366 my ($self, $info) = @_;
367 my @rest = @{$info->{rest}} if exists($info->{rest});
368 $self->get_user($info->{id}, @rest);
373 return $self->get_auth_realm('default')->{'store'};
376 ## BACKWARDS COMPATIBILITY
377 ## this only ever returns a hash containing 'default' - as that is the only
378 ## supported mode of calling this.
379 sub auth_store_names {
382 my %hash = ( $self->get_auth_realm('default')->{'store'} => 'default' );
386 my ( $self, $name ) = @_;
388 if ($name ne 'default') {
389 Carp::croak "get_auth_store called on non-default realm '$name'. Only default supported in compatibility mode";
391 $self->default_auth_store();
395 sub get_auth_store_name {
396 my ( $self, $store ) = @_;
400 # sub auth_stores is only used internally - here for completeness
404 my %hash = ( 'default' => $self->get_auth_realm('default')->{'store'});
415 Catalyst::Plugin::Authentication - Infrastructure plugin for the Catalyst
416 authentication framework.
425 $c->authenticate({ username => 'myusername', password => 'mypassword' });
426 my $age = $c->user->get('age');
431 The authentication plugin provides generic user support for Catalyst apps. It
432 is the basis for both authentication (checking the user is who they claim to
433 be), and authorization (allowing the user to do what the system authorises
436 Using authentication is split into two parts. A Store is used to actually
437 store the user information, and can store any amount of data related to the
438 user. Credentials are used to verify users, using information from the store,
439 given data from the frontend. A Credential and a Store are paired to form a
440 'Realm'. A Catalyst application using the authentication framework must have
441 at least one realm, and may have several.
443 To implement authentication in a Catalyst application you need to add this
444 module, and specify at least one realm in the configuration.
446 Authentication data can also be stored in a session, if the application
447 is using the L<Catalyst::Plugin::Session> module.
449 B<NOTE> in version 0.10 of this module, the interface to this module changed.
450 Please see L</COMPATIBILITY ROUTINES> for more information.
454 =head2 The Authentication/Authorization Process
456 Web applications typically need to identify a user - to tell the user apart
457 from other users. This is usually done in order to display private information
458 that is only that user's business, or to limit access to the application so
459 that only certain entities can access certain parts.
461 This process is split up into several steps. First you ask the user to identify
462 themselves. At this point you can't be sure that the user is really who they
465 Then the user tells you who they are, and backs this claim with some piece of
466 information that only the real user could give you. For example, a password is
467 a secret that is known to both the user and you. When the user tells you this
468 password you can assume they're in on the secret and can be trusted (ignore
469 identity theft for now). Checking the password, or any other proof is called
470 B<credential verification>.
472 By this time you know exactly who the user is - the user's identity is
473 B<authenticated>. This is where this module's job stops, and your application
474 or other plugins step in.
476 The next logical step is B<authorization>, the process of deciding what a user
477 is (or isn't) allowed to do. For example, say your users are split into two
478 main groups - regular users and administrators. You want to verify that the
479 currently logged in user is indeed an administrator before performing the
480 actions in an administrative part of your application. These decisionsmay be
481 made within your application code using just the information available after
482 authentication, or it may be facilitated by a number of plugins.
484 =head2 The Components In This Framework
488 Configuration of the Catalyst::Plugin::Authentication framework is done in
489 terms of realms. In simplest terms, a realm is a pairing of a Credential
490 verifier and a User storage (Store) backend.
492 An application can have any number of Realms, each of which operates
493 independant of the others. Each realm has a name, which is used to identify it
494 as the target of an authentication request. This name can be anything, such as
495 'users' or 'members'. One realm must be defined as the default_realm, which is
496 used when no realm name is specified. More information about configuring
497 realms is available in the configuration section.
499 =head3 Credential Verifiers
501 When user input is transferred to the L<Catalyst> application (typically via
502 form inputs) the application may pass this information into the authentication
503 system through the $c->authenticate() method. From there, it is passed to the
504 appropriate Credential verifier.
506 These plugins check the data, and ensure that it really proves the user is who
509 =head3 Storage Backends
511 The authentication data also identifies a user, and the Storage backend modules
512 use this data to locate and return a standardized object-oriented
513 representation of a user.
515 When a user is retrieved from a store it is not necessarily authenticated.
516 Credential verifiers accept a set of authentication data and use this
517 information to retrieve the user from the store they are paired with.
519 =head3 The Core Plugin
521 This plugin on its own is the glue, providing realm configuration, session
522 integration, and other goodness for the other plugins.
526 More layers of plugins can be stacked on top of the authentication code. For
527 example, L<Catalyst::Plugin::Session::PerUser> provides an abstraction of
528 browser sessions that is more persistent per users.
529 L<Catalyst::Plugin::Authorization::Roles> provides an accepted way to separate
530 and group users into categories, and then check which categories the current
535 Let's say we were storing users in a simple perl hash. Users are
536 verified by supplying a password which is matched within the hash.
538 This means that our application will begin like this:
546 __PACKAGE__->config->{authentication} =
548 default_realm => 'members',
558 password => "s00p3r",
560 roles => [qw/edit delete/],
563 password => "s3cr3t",
564 roles => [qw/comment/],
573 This tells the authentication plugin what realms are available, which
574 credential and store modules are used, and the configuration of each. With
575 this code loaded, we can now attempt to authenticate users.
577 To show an example of this, let's create an authentication controller:
579 package MyApp::Controller::Auth;
582 my ( $self, $c ) = @_;
584 if ( my $user = $c->req->param("user")
585 and my $password = $c->req->param("password") )
587 if ( $c->authenticate( { username => $user,
588 password => $password } ) ) {
589 $c->res->body( "hello " . $c->user->get("name") );
599 This code should be very readable. If all the necessary fields are supplied,
600 call the L<Catalyst::Plugin::Authentication/authenticate> method in the
601 controller. If it succeeds the user is logged in.
603 The credential verifier will attempt to retrieve the user whose details match
604 the authentication information provided to $c->authenticate(). Once it fetches
605 the user the password is checked and if it matches the user will be
606 B<authenticated> and C<< $c->user >> will contain the user object retrieved
609 In the above case, the default realm is checked, but we could just as easily
610 check an alternate realm. If this were an admin login, for example, we could
611 authenticate on the admin realm by simply changing the $c->authenticate()
614 if ( $c->authenticate( { username => $user,
615 password => $password }, 'admin' )l ) {
616 $c->res->body( "hello " . $c->user->get("name") );
620 Now suppose we want to restrict the ability to edit to a user with 'edit'
623 The restricted action might look like this:
626 my ( $self, $c ) = @_;
628 $c->detach("unauthorized")
629 unless $c->user_exists
630 and $c->user->get('editor') == 'yes';
632 # do something restricted here
635 This is somewhat similar to role based access control.
636 L<Catalyst::Plugin::Authentication::Store::Minimal> treats the roles field as
637 an array of role names. Let's leverage this. Add the role authorization
646 my ( $self, $c ) = @_;
648 $c->detach("unauthorized") unless $c->check_roles("edit");
650 # do something restricted here
653 This is somewhat simpler and will work if you change your store, too, since the
654 role interface is consistent.
656 Let's say your app grew, and you now have 10000 users. It's no longer
657 efficient to maintain a hash of users, so you move this data to a database.
658 You can accomplish this simply by installing the DBIx::Class Store and
659 changing your config:
661 __PACKAGE__->config->{authentication} =
663 default_realm => 'members',
670 class => 'DBIx::Class',
671 user_class => 'MyApp::Users',
672 role_column => 'roles'
678 The authentication system works behind the scenes to load your data from the
679 new source. The rest of your application is completely unchanged.
687 __PACKAGE__->config->{authentication} =
689 default_realm => 'members',
696 class => 'DBIx::Class',
697 user_class => 'MyApp::Users',
698 role_column => 'roles'
706 class => '+MyApp::Authentication::Store::NetAuth',
707 authserver => '192.168.10.17'
716 Whether or not to store the user's logged in state in the session, if the
717 application is also using L<Catalyst::Plugin::Session>. This
718 value is set to true per default.
722 This defines which realm should be used as when no realm is provided to methods
723 that require a realm such as authenticate or find_user.
727 This contains the series of realm configurations you want to use for your app.
728 The only rule here is that there must be at least one. A realm consists of a
729 name, which is used to reference the realm, a credential and a store.
731 Each realm config contains two hashes, one called 'credential' and one called
732 'store', each of which provide configuration details to the respective modules.
733 The contents of these hashes is specific to the module being used, with the
734 exception of the 'class' element, which tells the core Authentication module the
735 classname to instantiate.
737 The 'class' element follows the standard Catalyst mechanism of class
738 specification. If a class is prefixed with a +, it is assumed to be a complete
739 class name. Otherwise it is considered to be a portion of the class name. For
740 credentials, the classname 'B<Password>', for example, is expanded to
741 Catalyst::Plugin::Authentication::Credential::B<Password>. For stores, the
742 classname 'B<storename>' is expanded to:
743 Catalyst::Plugin::Authentication::Store::B<storename>.
753 =item authenticate( $userinfo, $realm )
755 Attempts to authenticate the user using the information in the $userinfo hash
756 reference using the realm $realm. $realm may be omitted, in which case the
757 default realm is checked.
761 Returns the currently logged in user or undef if there is none.
765 Returns true if a user is logged in right now. The difference between
766 user_exists and user is that user_exists will return true if a user is logged
767 in, even if it has not been yet retrieved from the storage backend. If you only
768 need to know if the user is logged in, depending on the storage mechanism this
769 can be much more efficient.
771 =item user_in_realm ( $realm )
773 Works like user_exists, except that it only returns true if a user is both
774 logged in right now and is from the realm provided.
778 Logs the user out, Deletes the currently logged in user from $c->user and the session.
780 =item find_user( $userinfo, $realm )
782 Fetch a particular users details, matching the provided user info, from the realm
787 =head1 INTERNAL METHODS
789 These methods are for Catalyst::Plugin::Authentication B<INTERNAL USE> only.
790 Please do not use them in your own code, whether application or credential /
791 store modules. If you do, you will very likely get the nasty shock of having
792 to fix / rewrite your code when things change. They are documented here only
797 =item set_authenticated ( $user, $realmname )
799 Marks a user as authenticated. This is called from within the authenticate
800 routine when a credential returns a user. $realmname defaults to 'default'
802 =item auth_restore_user ( $user, $realmname )
804 Used to restore a user from the session. In most cases this is called without
805 arguments to restore the user via the session. Can be called with arguments
806 when restoring a user from some other method. Currently not used in this way.
808 =item save_user_in_session ( $user, $realmname )
810 Used to save the user in a session. Saves $user in session, marked as
811 originating in $realmname. Both arguments are required.
815 Returns a hashref containing realmname -> realm instance pairs. Realm
816 instances contain an instantiated store and credential object as the 'store'
817 and 'credential' elements, respectively
819 =item get_auth_realm ( $realmname )
821 Retrieves the realm instance for the realmname provided.
829 This list might not be up to date. Below are modules known to work with the updated
830 API of 0.10 and are therefore compatible with realms.
832 =head2 User Storage Backends
834 L<Catalyst::Plugin::Authentication::Store::Minimal>,
835 L<Catalyst::Plugin::Authentication::Store::DBIx::Class>,
837 =head2 Credential verification
839 L<Catalyst::Plugin::Authentication::Credential::Password>,
843 L<Catalyst::Plugin::Authorization::ACL>,
844 L<Catalyst::Plugin::Authorization::Roles>
846 =head2 Internals Documentation
848 L<Catalyst::Plugin::Authentication::Internals>
852 L<Catalyst::Plugin::Session>,
853 L<Catalyst::Plugin::Session::PerUser>
855 =head1 DON'T SEE ALSO
857 This module along with its sub plugins deprecate a great number of other
858 modules. These include L<Catalyst::Plugin::Authentication::Simple>,
859 L<Catalyst::Plugin::Authentication::CDBI>.
861 At the time of writing these plugins have not yet been replaced or updated, but
862 should be eventually: L<Catalyst::Plugin::Authentication::OpenID>,
863 L<Catalyst::Plugin::Authentication::LDAP>,
864 L<Catalyst::Plugin::Authentication::CDBI::Basic>,
865 L<Catalyst::Plugin::Authentication::Basic::Remote>.
867 =head1 INCOMPATABILITIES
869 The realms based configuration and functionality of the 0.10 update
870 of L<Catalyst::Plugin::Authentication> required a change in the API used by
871 credentials and stores. It has a compatibility mode which allows use of
872 modules that have not yet been updated. This, however, completely mimics the
873 older api and disables the new realm-based features. In other words you can
874 not mix the older credential and store modules with realms, or realm-based
875 configs. The changes required to update modules are relatively minor and are
876 covered in L<Catalyst::Plugin::Authentication::Internals>. We hope that most
877 modules will move to the compatible list above very quickly.
879 =head1 COMPATIBILITY ROUTINES
881 In version 0.10 of L<Catalyst::Plugin::Authentication>, the API
882 changed. For app developers, this change is fairly minor, but for
883 Credential and Store authors, the changes are significant.
885 Please see the documentation in version 0.09 of
886 Catalyst::Plugin::Authentication for a better understanding of how the old API
889 The items below are still present in the plugin, though using them is
890 deprecated. They remain only as a transition tool, for those sites which can
891 not yet be upgraded to use the new system due to local customizations or use
892 of Credential / Store modules that have not yet been updated to work with the
895 These routines should not be used in any application using realms
896 functionality or any of the methods described above. These are for reference
903 This method is used to initiate authentication and user retrieval. Technically
904 this is part of the old Password credential module and it still resides in the
905 L<Password|Catalyst::Plugin::Authentication::Credential::Password> class. It is
906 included here for reference only.
908 =item default_auth_store
910 Return the store whose name is 'default'.
912 This is set to C<< $c->config->{authentication}{store} >> if that value exists,
913 or by using a Store plugin:
915 # load the Minimal authentication store.
916 use Catalyst qw/Authentication Authentication::Store::Minimal/;
918 Sets the default store to
919 L<Catalyst::Plugin::Authentication::Store::Minimal>.
921 =item get_auth_store $name
923 Return the store whose name is $name.
925 =item get_auth_store_name $store
927 Return the name of the store $store.
931 A hash keyed by name, with the stores registered in the app.
933 =item register_auth_stores %stores_by_name
935 Register stores into the application.
943 Yuval Kogman, C<nothingmuch@woobling.org>
945 Jay Kuri, C<jayk@cpan.org>
952 =head1 COPYRIGHT & LICENSE
954 Copyright (c) 2005 the aforementioned authors. All rights
955 reserved. This program is free software; you can redistribute
956 it and/or modify it under the same terms as Perl itself.