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.05";
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);
52 if ( $user and !Scalar::Util::blessed($user) ) {
53 # return 1 if have_want() && Want::want("BOOL");
54 return $c->auth_restore_user($user);
62 return defined($c->_user);
65 sub save_user_in_session {
66 my ( $c, $user ) = @_;
68 my $store = $user->store || ref $user;
69 $c->session->{__user_store} = $c->get_auth_store_name($store) || $store;
70 $c->session->{__user} = $user->for_session;
78 if ( $c->isa("Catalyst::Plugin::Session")
79 and $c->config->{authentication}{use_session} )
81 delete @{ $c->session }{qw/__user __user_store/};
88 my ( $c, $uid, @rest ) = @_;
90 if ( my $store = $c->default_auth_store ) {
91 return $store->get_user( $uid, @rest );
94 Catalyst::Exception->throw(
95 "The user id $uid was passed to an authentication "
96 . "plugin, but no default store was specified" );
101 my $c = shift->NEXT::prepare(@_);
103 if ( $c->isa("Catalyst::Plugin::Session")
106 if ( $c->sessionid and my $frozen_user = $c->session->{__user} ) {
107 $c->_user($frozen_user);
114 sub auth_restore_user {
115 my ( $c, $frozen_user, $store_name ) = @_;
118 unless $c->isa("Catalyst::Plugin::Session")
119 and $c->config->{authentication}{use_session}
122 $store_name ||= $c->session->{__user_store};
123 $frozen_user ||= $c->session->{__user};
125 my $store = $c->get_auth_store($store_name);
126 $c->_user( my $user = $store->from_session( $c, $frozen_user ) );
135 my $cfg = $c->config->{authentication} || {};
142 $c->register_auth_stores(
143 default => $cfg->{store},
144 %{ $cfg->{stores} || {} },
151 my ( $self, $name ) = @_;
152 $self->auth_stores->{$name} || ( Class::Inspector->loaded($name) && $name );
155 sub get_auth_store_name {
156 my ( $self, $store ) = @_;
157 $self->auth_store_names->{$store};
160 sub register_auth_stores {
161 my ( $self, %new ) = @_;
163 foreach my $name ( keys %new ) {
164 my $store = $new{$name} or next;
165 $self->auth_stores->{$name} = $store;
166 $self->auth_store_names->{$store} = $name;
172 $self->_auth_stores(@_) || $self->_auth_stores( {} );
175 sub auth_store_names {
178 $self->_auth_store_names || do {
179 tie my %hash, 'Tie::RefHash';
180 $self->_auth_store_names( \%hash );
184 sub default_auth_store {
187 if ( my $new = shift ) {
188 $self->register_auth_stores( default => $new );
191 $self->get_auth_store("default");
202 Catalyst::Plugin::Authentication - Infrastructure plugin for the Catalyst
203 authentication framework.
209 Authentication::Store::Foo
210 Authentication::Credential::Password
214 # ->login is provided by the Credential::Password module
215 $c->login('myusername', 'mypassword');
216 my $age = $c->user->age;
221 The authentication plugin provides generic user support. It is the basis
222 for both authentication (checking the user is who they claim to be), and
223 authorization (allowing the user to do what the system authorises them to do).
225 Using authentication is split into two parts. A Store is used to actually
226 store the user information, and can store any amount of data related to
227 the user. Multiple stores can be accessed from within one application.
228 Credentials are used to verify users, using the store, given data from
231 To implement authentication in a Catalyst application you need to add this
232 module, plus at least one store and one credential module.
234 Authentication data can also be stored in a session, if the application
235 is using the L<Catalyst::Plugin::Session> module.
239 =head2 The Authentication/Authorization Process
241 Web applications typically need to identify a user - to tell the user apart
242 from other users. This is usually done in order to display private information
243 that is only that user's business, or to limit access to the application so
244 that only certain entities can access certain parts.
246 This process is split up into several steps. First you ask the user to identify
247 themselves. At this point you can't be sure that the user is really who they
250 Then the user tells you who they are, and backs this claim with some piece of
251 information that only the real user could give you. For example, a password is
252 a secret that is known to both the user and you. When the user tells you this
253 password you can assume they're in on the secret and can be trusted (ignore
254 identity theft for now). Checking the password, or any other proof is called
255 B<credential verification>.
257 By this time you know exactly who the user is - the user's identity is
258 B<authenticated>. This is where this module's job stops, and other plugins step
259 in. The next logical step is B<authorization>, the process of deciding what a
260 user is (or isn't) allowed to do. For example, say your users are split into
261 two main groups - regular users and administrators. You should verify that the
262 currently logged in user is indeed an administrator before performing the
263 actions of an administrative part of your application. One way to do this is
264 with role based access control.
266 =head2 The Components In This Framework
268 =head3 Credential Verifiers
270 When user input is transferred to the L<Catalyst> application (typically via
271 form inputs) this data then enters the authentication framework through these
274 These plugins check the data, and ensure that it really proves the user is who
277 =head3 Storage Backends
279 The credentials also identify a user, and this family of modules is supposed to
280 take this identification data and return a standardized object oriented
281 representation of users.
283 When a user is retrieved from a store it is not necessarily authenticated.
284 Credential verifiers can either accept a user object, or fetch the object
285 themselves from the default store.
287 =head3 The Core Plugin
289 This plugin on its own is the glue, providing store registration, session
290 integration, and other goodness for the other plugins.
294 More layers of plugins can be stacked on top of the authentication code. For
295 example, L<Catalyst::Plugin::Session::PerUser> provides an abstraction of
296 browser sessions that is more persistent per users.
297 L<Catalyst::Plugin::Authorization::Roles> provides an accepted way to separate
298 and group users into categories, and then check which categories the current
303 Let's say we were storing users in an Apache style htpasswd file. Users are
304 stored in that file, with a hashed password and some extra comments. Users are
305 verified by supplying a password which is matched with the file.
307 This means that our application will begin like this:
313 Authentication::Credential::Password
314 Authentication::Store::Htpasswd
317 __PACKAGE__->config->{authentication}{htpasswd} = "passwdfile";
319 This loads the appropriate methods and also sets the htpasswd store as the
322 So, now that we have the code loaded we need to get data from the user into the
325 Let's create an authentication controller:
327 package MyApp::Controller::Auth;
330 my ( $self, $c ) = @_;
332 if ( my $user = $c->req->param("user")
333 and my $password = $c->req->param("password") )
335 if ( $c->login( $user, $password ) ) {
336 $c->res->body( "hello " . $c->user->name );
346 This code should be very readable. If all the necessary fields are supplied,
347 call the L<Authentication::Credential::Password/login> method on the
348 controller. If that succeeds the user is logged in.
350 It could be simplified though:
353 my ( $self, $c ) = @_;
360 Since the C<login> method knows how to find logically named parameters on it's
363 The credential verifier will ask the default store to get the user whose ID is
364 the user parameter. In this case the default store is the htpasswd one. Once it
365 fetches the user from the store the password is checked and if it's OK
366 C<< $c->user >> will contain the user object returned from the htpasswd store.
368 We can also pass a user object to the credential verifier manually, if we have
369 several stores per app. This is discussed in
370 L<Catalyst::Plugin::Authentication::Store>.
372 Now imagine each admin user has a comment set in the htpasswd file saying
375 A restricted action might look like this:
377 sub restricted : Local {
378 my ( $self, $c ) = @_;
380 $c->detach("unauthorized")
381 unless $c->user_exists
382 and $c->user->extra_info() eq "admin";
384 # do something restricted here
387 This is somewhat similar to role based access control.
388 L<Catalyst::Plugin::Authentication::Store::Htpasswd> treats the extra info
389 field as a comma separated list of roles if it's treated that way. Let's
390 leverage this. Add the role authorization plugin:
397 sub restricted : Local {
398 my ( $self, $c ) = @_;
400 $c->detach("unauthorized") unless $c->check_roles("admin");
402 # do something restricted here
405 This is somewhat simpler and will work if you change your store, too, since the
406 role interface is consistent.
408 Let's say your app grew, and you now have 10000 users. It's no longer efficient
409 to maintain an htpasswd file, so you move this data to a database.
413 Authentication::Credential::Password
414 Authentication::Store::DBIC
418 __PACKAGE__->config->{authentication}{dbic} = ...; # see the DBIC store docs
420 The rest of your code should be unchanged. Now let's say you are integrating
421 typekey authentication to your system. For simplicity's sake we'll assume that
422 the user's are still keyed in the same way.
426 Authentication::Credential::Password
427 Authentication::Credential::TypeKey
428 Authentication::Store::DBIC
432 And in your auth controller add a new action:
434 sub typekey : Local {
435 my ( $self, $c ) = @_;
437 if ( $c->authenticate_typekey) { # uses $c->req and Authen::TypeKey
438 # same stuff as the $c->login method
443 You've now added a new credential verification mechanizm orthogonally to the
444 other components. All you have to do is make sure that the credential verifiers
445 pass on the same types of parameters to the store in order to retrieve user
454 Returns the currently logged in user or undef if there is none.
458 Whether or not a user is logged in right now.
460 The reason this method exists is that C<< $c->user >> may needlessly load the
461 user from the auth store.
463 If you're just going to say
465 if ( $c->user_exists ) {
468 $c->forward("login");
471 it should be more efficient than C<< $c->user >> when a user is marked in the
472 session but C<< $c->user >> hasn't been called yet.
476 Delete the currently logged in user from C<user> and the session.
480 Fetch a particular users details, defined by the given ID, via the default store.
490 Whether or not to store the user's logged in state in the session, if the
491 application is also using the L<Catalyst::Plugin::Session> plugin. This
492 value is set to true per default.
496 If multiple stores are being used, set the module you want as default here.
500 If multiple stores are being used, you need to provide a name for each store
501 here, as a hash, the keys are the names you wish to use, and the values are
502 the the names of the plugins.
505 __PACKAGE__->config( authentication => {
506 store => 'Catalyst::Plugin::Authentication::Store::HtPasswd',
508 'dbic' => 'Catalyst::Plugin::Authentication::Store::DBIC'
514 =head1 METHODS FOR STORE MANAGEMENT
518 =item default_auth_store
520 Return the store whose name is 'default'.
522 This is set to C<< $c->config->{authentication}{store} >> if that value exists,
523 or by using a Store plugin:
525 use Catalyst qw/Authentication Authentication::Store::Minimal/;
527 Sets the default store to
528 L<Catalyst::Plugin::Authentication::Store::Minimal::Backend>.
531 =item get_auth_store $name
533 Return the store whose name is $name.
535 =item get_auth_store_name $store
537 Return the name of the store $store.
541 A hash keyed by name, with the stores registered in the app.
543 =item auth_store_names
545 A ref-hash keyed by store, which contains the names of the stores.
547 =item register_auth_stores %stores_by_name
549 Register stores into the application.
553 =head1 INTERNAL METHODS
557 =item set_authenticated $user
559 Marks a user as authenticated. Should be called from a
560 C<Catalyst::Plugin::Authentication::Credential> plugin after successful
563 This involves setting C<user> and the internal data in C<session> if
564 L<Catalyst::Plugin::Session> is loaded.
566 =item auth_restore_user $user
568 Used to restore a user from the session, by C<user> only when it's actually
571 =item save_user_in_session $user
573 Used to save the user in a session.
577 Revives a user from the session object if there is one.
581 Sets the default configuration parameters.
589 This list might not be up to date.
591 =head2 User Storage Backends
593 L<Catalyst::Plugin::Authentication::Store::Minimal>,
594 L<Catalyst::Plugin::Authentication::Store::Htpasswd>,
595 L<Catalyst::Plugin::Authentication::Store::DBIC> (also works with Class::DBI).
597 =head2 Credential verification
599 L<Catalyst::Plugin::Authentication::Credential::Password>,
600 L<Catalyst::Plugin::Authentication::Credential::HTTP>,
601 L<Catalyst::Plugin::Authentication::Credential::TypeKey>
605 L<Catalyst::Plugin::Authorization::ACL>,
606 L<Catalyst::Plugin::Authorization::Roles>
608 =head2 Internals Documentation
610 L<Catalyst::Plugin::Authentication::Store>
614 L<Catalyst::Plugin::Session>,
615 L<Catalyst::Plugin::Session::PerUser>
617 =head1 DON'T SEE ALSO
619 This module along with its sub plugins deprecate a great number of other
620 modules. These include L<Catalyst::Plugin::Authentication::Simple>,
621 L<Catalyst::Plugin::Authentication::CDBI>.
623 At the time of writing these plugins have not yet been replaced or updated, but
624 should be eventually: L<Catalyst::Plugin::Authentication::OpenID>,
625 L<Catalyst::Plugin::Authentication::LDAP>,
626 L<Catalyst::Plugin::Authentication::CDBI::Basic>,
627 L<Catalyst::Plugin::Authentication::Basic::Remote>.
631 Yuval Kogman, C<nothingmuch@woobling.org>
637 =head1 COPYRIGHT & LICENSE
639 Copyright (c) 2005 the aforementioned authors. All rights
640 reserved. This program is free software; you can redistribute
641 it and/or modify it under the same terms as Perl itself.