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_stores _auth_store_names/;
18 # this optimization breaks under Template::Toolkit
19 # use user_exists instead
22 # constant->import(have_want => eval { require Want });
25 our $VERSION = "0.09";
27 sub set_authenticated {
28 my ( $c, $user ) = @_;
31 $c->request->{user} = $user; # compatibility kludge
33 if ( $c->isa("Catalyst::Plugin::Session")
34 and $c->config->{authentication}{use_session}
35 and $user->supports("session") )
37 $c->save_user_in_session($user);
40 $c->NEXT::set_authenticated($user);
50 if ( defined(my $user = $c->_user) ) {
53 return $c->auth_restore_user;
59 return defined($c->_user) || defined($c->_user_in_session);
62 sub save_user_in_session {
63 my ( $c, $user ) = @_;
65 my $store = $user->store || ref $user;
66 $c->session->{__user_store} = $c->get_auth_store_name($store) || $store;
67 $c->session->{__user} = $user->for_session;
76 $c->isa("Catalyst::Plugin::Session")
77 and $c->config->{authentication}{use_session}
78 and $c->session_is_valid
80 delete @{ $c->session }{qw/__user __user_store/};
87 my ( $c, $uid, @rest ) = @_;
89 if ( my $store = $c->default_auth_store ) {
90 return $store->get_user( $uid, @rest );
93 Catalyst::Exception->throw(
94 "The user id $uid was passed to an authentication "
95 . "plugin, but no default store was specified" );
99 sub _user_in_session {
103 $c->isa("Catalyst::Plugin::Session")
104 and $c->config->{authentication}{use_session}
105 and $c->session_is_valid;
107 return $c->session->{__user};
112 sub auth_restore_user {
113 my ( $c, $frozen_user, $store_name ) = @_;
115 $frozen_user ||= $c->_user_in_session;
116 return unless defined($frozen_user);
118 $store_name ||= $c->session->{__user_store};
119 return unless $store_name; # FIXME die unless? This is an internal inconsistency
121 my $store = $c->get_auth_store($store_name);
122 $c->_user( my $user = $store->from_session( $c, $frozen_user ) );
131 my $cfg = $c->config->{authentication} || {};
138 $c->register_auth_stores(
139 default => $cfg->{store},
140 %{ $cfg->{stores} || {} },
147 my ( $self, $name ) = @_;
148 $self->auth_stores->{$name} || ( Class::Inspector->loaded($name) && $name );
151 sub get_auth_store_name {
152 my ( $self, $store ) = @_;
153 $self->auth_store_names->{$store};
156 sub register_auth_stores {
157 my ( $self, %new ) = @_;
159 foreach my $name ( keys %new ) {
160 my $store = $new{$name} or next;
161 $self->auth_stores->{$name} = $store;
162 $self->auth_store_names->{$store} = $name;
168 $self->_auth_stores(@_) || $self->_auth_stores( {} );
171 sub auth_store_names {
174 $self->_auth_store_names || do {
175 tie my %hash, 'Tie::RefHash';
176 $self->_auth_store_names( \%hash );
180 sub default_auth_store {
183 if ( my $new = shift ) {
184 $self->register_auth_stores( default => $new );
187 $self->get_auth_store("default");
198 Catalyst::Plugin::Authentication - Infrastructure plugin for the Catalyst
199 authentication framework.
205 Authentication::Store::Foo
206 Authentication::Credential::Password
210 # ->login is provided by the Credential::Password module
211 $c->login('myusername', 'mypassword');
212 my $age = $c->user->age;
217 The authentication plugin provides generic user support. It is the basis
218 for both authentication (checking the user is who they claim to be), and
219 authorization (allowing the user to do what the system authorises them to do).
221 Using authentication is split into two parts. A Store is used to actually
222 store the user information, and can store any amount of data related to
223 the user. Multiple stores can be accessed from within one application.
224 Credentials are used to verify users, using the store, given data from
227 To implement authentication in a Catalyst application you need to add this
228 module, plus at least one store and one credential module.
230 Authentication data can also be stored in a session, if the application
231 is using the L<Catalyst::Plugin::Session> module.
235 =head2 The Authentication/Authorization Process
237 Web applications typically need to identify a user - to tell the user apart
238 from other users. This is usually done in order to display private information
239 that is only that user's business, or to limit access to the application so
240 that only certain entities can access certain parts.
242 This process is split up into several steps. First you ask the user to identify
243 themselves. At this point you can't be sure that the user is really who they
246 Then the user tells you who they are, and backs this claim with some piece of
247 information that only the real user could give you. For example, a password is
248 a secret that is known to both the user and you. When the user tells you this
249 password you can assume they're in on the secret and can be trusted (ignore
250 identity theft for now). Checking the password, or any other proof is called
251 B<credential verification>.
253 By this time you know exactly who the user is - the user's identity is
254 B<authenticated>. This is where this module's job stops, and other plugins step
255 in. The next logical step is B<authorization>, the process of deciding what a
256 user is (or isn't) allowed to do. For example, say your users are split into
257 two main groups - regular users and administrators. You should verify that the
258 currently logged in user is indeed an administrator before performing the
259 actions of an administrative part of your application. One way to do this is
260 with role based access control.
262 =head2 The Components In This Framework
264 =head3 Credential Verifiers
266 When user input is transferred to the L<Catalyst> application (typically via
267 form inputs) this data then enters the authentication framework through these
270 These plugins check the data, and ensure that it really proves the user is who
273 =head3 Storage Backends
275 The credentials also identify a user, and this family of modules is supposed to
276 take this identification data and return a standardized object oriented
277 representation of users.
279 When a user is retrieved from a store it is not necessarily authenticated.
280 Credential verifiers can either accept a user object, or fetch the object
281 themselves from the default store.
283 =head3 The Core Plugin
285 This plugin on its own is the glue, providing store registration, session
286 integration, and other goodness for the other plugins.
290 More layers of plugins can be stacked on top of the authentication code. For
291 example, L<Catalyst::Plugin::Session::PerUser> provides an abstraction of
292 browser sessions that is more persistent per users.
293 L<Catalyst::Plugin::Authorization::Roles> provides an accepted way to separate
294 and group users into categories, and then check which categories the current
299 Let's say we were storing users in an Apache style htpasswd file. Users are
300 stored in that file, with a hashed password and some extra comments. Users are
301 verified by supplying a password which is matched with the file.
303 This means that our application will begin like this:
309 Authentication::Credential::Password
310 Authentication::Store::Htpasswd
313 __PACKAGE__->config->{authentication}{htpasswd} = "passwdfile";
315 This loads the appropriate methods and also sets the htpasswd store as the
318 So, now that we have the code loaded we need to get data from the user into the
321 Let's create an authentication controller:
323 package MyApp::Controller::Auth;
326 my ( $self, $c ) = @_;
328 if ( my $user = $c->req->param("user")
329 and my $password = $c->req->param("password") )
331 if ( $c->login( $user, $password ) ) {
332 $c->res->body( "hello " . $c->user->name );
342 This code should be very readable. If all the necessary fields are supplied,
343 call the L<Authentication::Credential::Password/login> method on the
344 controller. If that succeeds the user is logged in.
346 It could be simplified though:
349 my ( $self, $c ) = @_;
356 Since the C<login> method knows how to find logically named parameters on its
359 The credential verifier will ask the default store to get the user whose ID is
360 the user parameter. In this case the default store is the htpasswd one. Once it
361 fetches the user from the store the password is checked and if it's OK
362 C<< $c->user >> will contain the user object returned from the htpasswd store.
364 We can also pass a user object to the credential verifier manually, if we have
365 several stores per app. This is discussed in
366 L<Catalyst::Plugin::Authentication::Store>.
368 Now imagine each admin user has a comment set in the htpasswd file saying
371 A restricted action might look like this:
373 sub restricted : Local {
374 my ( $self, $c ) = @_;
376 $c->detach("unauthorized")
377 unless $c->user_exists
378 and $c->user->extra_info() eq "admin";
380 # do something restricted here
383 This is somewhat similar to role based access control.
384 L<Catalyst::Plugin::Authentication::Store::Htpasswd> treats the extra info
385 field as a comma separated list of roles if it's treated that way. Let's
386 leverage this. Add the role authorization plugin:
393 sub restricted : Local {
394 my ( $self, $c ) = @_;
396 $c->detach("unauthorized") unless $c->check_roles("admin");
398 # do something restricted here
401 This is somewhat simpler and will work if you change your store, too, since the
402 role interface is consistent.
404 Let's say your app grew, and you now have 10000 users. It's no longer efficient
405 to maintain an htpasswd file, so you move this data to a database.
409 Authentication::Credential::Password
410 Authentication::Store::DBIC
414 __PACKAGE__->config->{authentication}{dbic} = ...; # see the DBIC store docs
416 The rest of your code should be unchanged. Now let's say you are integrating
417 typekey authentication to your system. For simplicity's sake we'll assume that
418 the user's are still keyed in the same way.
422 Authentication::Credential::Password
423 Authentication::Credential::TypeKey
424 Authentication::Store::DBIC
428 And in your auth controller add a new action:
430 sub typekey : Local {
431 my ( $self, $c ) = @_;
433 if ( $c->authenticate_typekey) { # uses $c->req and Authen::TypeKey
434 # same stuff as the $c->login method
439 You've now added a new credential verification mechanizm orthogonally to the
440 other components. All you have to do is make sure that the credential verifiers
441 pass on the same types of parameters to the store in order to retrieve user
450 Returns the currently logged in user or undef if there is none.
454 Whether or not a user is logged in right now.
456 The reason this method exists is that C<< $c->user >> may needlessly load the
457 user from the auth store.
459 If you're just going to say
461 if ( $c->user_exists ) {
464 $c->forward("login");
467 it should be more efficient than C<< $c->user >> when a user is marked in the
468 session but C<< $c->user >> hasn't been called yet.
472 Delete the currently logged in user from C<user> and the session.
476 Fetch a particular users details, defined by the given ID, via the default store.
486 Whether or not to store the user's logged in state in the session, if the
487 application is also using the L<Catalyst::Plugin::Session> plugin. This
488 value is set to true per default.
492 If multiple stores are being used, set the module you want as default here.
496 If multiple stores are being used, you need to provide a name for each store
497 here, as a hash, the keys are the names you wish to use, and the values are
498 the the names of the plugins.
501 __PACKAGE__->config( authentication => {
502 store => 'Catalyst::Plugin::Authentication::Store::HtPasswd',
504 'dbic' => 'Catalyst::Plugin::Authentication::Store::DBIC'
510 =head1 METHODS FOR STORE MANAGEMENT
514 =item default_auth_store
516 Return the store whose name is 'default'.
518 This is set to C<< $c->config->{authentication}{store} >> if that value exists,
519 or by using a Store plugin:
521 use Catalyst qw/Authentication Authentication::Store::Minimal/;
523 Sets the default store to
524 L<Catalyst::Plugin::Authentication::Store::Minimal::Backend>.
527 =item get_auth_store $name
529 Return the store whose name is $name.
531 =item get_auth_store_name $store
533 Return the name of the store $store.
537 A hash keyed by name, with the stores registered in the app.
539 =item auth_store_names
541 A ref-hash keyed by store, which contains the names of the stores.
543 =item register_auth_stores %stores_by_name
545 Register stores into the application.
549 =head1 INTERNAL METHODS
553 =item set_authenticated $user
555 Marks a user as authenticated. Should be called from a
556 C<Catalyst::Plugin::Authentication::Credential> plugin after successful
559 This involves setting C<user> and the internal data in C<session> if
560 L<Catalyst::Plugin::Session> is loaded.
562 =item auth_restore_user $user
564 Used to restore a user from the session, by C<user> only when it's actually
567 =item save_user_in_session $user
569 Used to save the user in a session.
573 Revives a user from the session object if there is one.
577 Sets the default configuration parameters.
585 This list might not be up to date.
587 =head2 User Storage Backends
589 L<Catalyst::Plugin::Authentication::Store::Minimal>,
590 L<Catalyst::Plugin::Authentication::Store::Htpasswd>,
591 L<Catalyst::Plugin::Authentication::Store::DBIC> (also works with Class::DBI).
593 =head2 Credential verification
595 L<Catalyst::Plugin::Authentication::Credential::Password>,
596 L<Catalyst::Plugin::Authentication::Credential::HTTP>,
597 L<Catalyst::Plugin::Authentication::Credential::TypeKey>
601 L<Catalyst::Plugin::Authorization::ACL>,
602 L<Catalyst::Plugin::Authorization::Roles>
604 =head2 Internals Documentation
606 L<Catalyst::Plugin::Authentication::Store>
610 L<Catalyst::Plugin::Session>,
611 L<Catalyst::Plugin::Session::PerUser>
613 =head1 DON'T SEE ALSO
615 This module along with its sub plugins deprecate a great number of other
616 modules. These include L<Catalyst::Plugin::Authentication::Simple>,
617 L<Catalyst::Plugin::Authentication::CDBI>.
619 At the time of writing these plugins have not yet been replaced or updated, but
620 should be eventually: L<Catalyst::Plugin::Authentication::OpenID>,
621 L<Catalyst::Plugin::Authentication::LDAP>,
622 L<Catalyst::Plugin::Authentication::CDBI::Basic>,
623 L<Catalyst::Plugin::Authentication::Basic::Remote>.
627 Yuval Kogman, C<nothingmuch@woobling.org>
633 =head1 COPYRIGHT & LICENSE
635 Copyright (c) 2005 the aforementioned authors. All rights
636 reserved. This program is free software; you can redistribute
637 it and/or modify it under the same terms as Perl itself.