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.08";
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 my $frozen = $c->_user_in_session;
54 return $c->auth_restore_user($frozen);
60 return defined($c->_user) || defined($c->_user_in_session);
63 sub _user_in_session {
66 if ( $c->isa("Catalyst::Plugin::Session") and $c->session_is_valid ) {
67 return $c->session->{__user};
73 sub save_user_in_session {
74 my ( $c, $user ) = @_;
76 my $store = $user->store || ref $user;
77 $c->session->{__user_store} = $c->get_auth_store_name($store) || $store;
78 $c->session->{__user} = $user->for_session;
86 if ( $c->isa("Catalyst::Plugin::Session")
87 and $c->config->{authentication}{use_session} )
89 delete @{ $c->session }{qw/__user __user_store/};
96 my ( $c, $uid, @rest ) = @_;
98 if ( my $store = $c->default_auth_store ) {
99 return $store->get_user( $uid, @rest );
102 Catalyst::Exception->throw(
103 "The user id $uid was passed to an authentication "
104 . "plugin, but no default store was specified" );
108 sub auth_restore_user {
109 my ( $c, $frozen_user, $store_name ) = @_;
112 unless $c->isa("Catalyst::Plugin::Session")
113 and $c->config->{authentication}{use_session}
116 $store_name ||= $c->session->{__user_store};
117 $frozen_user ||= $c->session->{__user};
119 my $store = $c->get_auth_store($store_name);
120 $c->_user( my $user = $store->from_session( $c, $frozen_user ) );
129 my $cfg = $c->config->{authentication} || {};
136 $c->register_auth_stores(
137 default => $cfg->{store},
138 %{ $cfg->{stores} || {} },
145 my ( $self, $name ) = @_;
146 $self->auth_stores->{$name} || ( Class::Inspector->loaded($name) && $name );
149 sub get_auth_store_name {
150 my ( $self, $store ) = @_;
151 $self->auth_store_names->{$store};
154 sub register_auth_stores {
155 my ( $self, %new ) = @_;
157 foreach my $name ( keys %new ) {
158 my $store = $new{$name} or next;
159 $self->auth_stores->{$name} = $store;
160 $self->auth_store_names->{$store} = $name;
166 $self->_auth_stores(@_) || $self->_auth_stores( {} );
169 sub auth_store_names {
172 $self->_auth_store_names || do {
173 tie my %hash, 'Tie::RefHash';
174 $self->_auth_store_names( \%hash );
178 sub default_auth_store {
181 if ( my $new = shift ) {
182 $self->register_auth_stores( default => $new );
185 $self->get_auth_store("default");
196 Catalyst::Plugin::Authentication - Infrastructure plugin for the Catalyst
197 authentication framework.
203 Authentication::Store::Foo
204 Authentication::Credential::Password
208 # ->login is provided by the Credential::Password module
209 $c->login('myusername', 'mypassword');
210 my $age = $c->user->age;
215 The authentication plugin provides generic user support. It is the basis
216 for both authentication (checking the user is who they claim to be), and
217 authorization (allowing the user to do what the system authorises them to do).
219 Using authentication is split into two parts. A Store is used to actually
220 store the user information, and can store any amount of data related to
221 the user. Multiple stores can be accessed from within one application.
222 Credentials are used to verify users, using the store, given data from
225 To implement authentication in a Catalyst application you need to add this
226 module, plus at least one store and one credential module.
228 Authentication data can also be stored in a session, if the application
229 is using the L<Catalyst::Plugin::Session> module.
233 =head2 The Authentication/Authorization Process
235 Web applications typically need to identify a user - to tell the user apart
236 from other users. This is usually done in order to display private information
237 that is only that user's business, or to limit access to the application so
238 that only certain entities can access certain parts.
240 This process is split up into several steps. First you ask the user to identify
241 themselves. At this point you can't be sure that the user is really who they
244 Then the user tells you who they are, and backs this claim with some piece of
245 information that only the real user could give you. For example, a password is
246 a secret that is known to both the user and you. When the user tells you this
247 password you can assume they're in on the secret and can be trusted (ignore
248 identity theft for now). Checking the password, or any other proof is called
249 B<credential verification>.
251 By this time you know exactly who the user is - the user's identity is
252 B<authenticated>. This is where this module's job stops, and other plugins step
253 in. The next logical step is B<authorization>, the process of deciding what a
254 user is (or isn't) allowed to do. For example, say your users are split into
255 two main groups - regular users and administrators. You should verify that the
256 currently logged in user is indeed an administrator before performing the
257 actions of an administrative part of your application. One way to do this is
258 with role based access control.
260 =head2 The Components In This Framework
262 =head3 Credential Verifiers
264 When user input is transferred to the L<Catalyst> application (typically via
265 form inputs) this data then enters the authentication framework through these
268 These plugins check the data, and ensure that it really proves the user is who
271 =head3 Storage Backends
273 The credentials also identify a user, and this family of modules is supposed to
274 take this identification data and return a standardized object oriented
275 representation of users.
277 When a user is retrieved from a store it is not necessarily authenticated.
278 Credential verifiers can either accept a user object, or fetch the object
279 themselves from the default store.
281 =head3 The Core Plugin
283 This plugin on its own is the glue, providing store registration, session
284 integration, and other goodness for the other plugins.
288 More layers of plugins can be stacked on top of the authentication code. For
289 example, L<Catalyst::Plugin::Session::PerUser> provides an abstraction of
290 browser sessions that is more persistent per users.
291 L<Catalyst::Plugin::Authorization::Roles> provides an accepted way to separate
292 and group users into categories, and then check which categories the current
297 Let's say we were storing users in an Apache style htpasswd file. Users are
298 stored in that file, with a hashed password and some extra comments. Users are
299 verified by supplying a password which is matched with the file.
301 This means that our application will begin like this:
307 Authentication::Credential::Password
308 Authentication::Store::Htpasswd
311 __PACKAGE__->config->{authentication}{htpasswd} = "passwdfile";
313 This loads the appropriate methods and also sets the htpasswd store as the
316 So, now that we have the code loaded we need to get data from the user into the
319 Let's create an authentication controller:
321 package MyApp::Controller::Auth;
324 my ( $self, $c ) = @_;
326 if ( my $user = $c->req->param("user")
327 and my $password = $c->req->param("password") )
329 if ( $c->login( $user, $password ) ) {
330 $c->res->body( "hello " . $c->user->name );
340 This code should be very readable. If all the necessary fields are supplied,
341 call the L<Authentication::Credential::Password/login> method on the
342 controller. If that succeeds the user is logged in.
344 It could be simplified though:
347 my ( $self, $c ) = @_;
354 Since the C<login> method knows how to find logically named parameters on its
357 The credential verifier will ask the default store to get the user whose ID is
358 the user parameter. In this case the default store is the htpasswd one. Once it
359 fetches the user from the store the password is checked and if it's OK
360 C<< $c->user >> will contain the user object returned from the htpasswd store.
362 We can also pass a user object to the credential verifier manually, if we have
363 several stores per app. This is discussed in
364 L<Catalyst::Plugin::Authentication::Store>.
366 Now imagine each admin user has a comment set in the htpasswd file saying
369 A restricted action might look like this:
371 sub restricted : Local {
372 my ( $self, $c ) = @_;
374 $c->detach("unauthorized")
375 unless $c->user_exists
376 and $c->user->extra_info() eq "admin";
378 # do something restricted here
381 This is somewhat similar to role based access control.
382 L<Catalyst::Plugin::Authentication::Store::Htpasswd> treats the extra info
383 field as a comma separated list of roles if it's treated that way. Let's
384 leverage this. Add the role authorization plugin:
391 sub restricted : Local {
392 my ( $self, $c ) = @_;
394 $c->detach("unauthorized") unless $c->check_roles("admin");
396 # do something restricted here
399 This is somewhat simpler and will work if you change your store, too, since the
400 role interface is consistent.
402 Let's say your app grew, and you now have 10000 users. It's no longer efficient
403 to maintain an htpasswd file, so you move this data to a database.
407 Authentication::Credential::Password
408 Authentication::Store::DBIC
412 __PACKAGE__->config->{authentication}{dbic} = ...; # see the DBIC store docs
414 The rest of your code should be unchanged. Now let's say you are integrating
415 typekey authentication to your system. For simplicity's sake we'll assume that
416 the user's are still keyed in the same way.
420 Authentication::Credential::Password
421 Authentication::Credential::TypeKey
422 Authentication::Store::DBIC
426 And in your auth controller add a new action:
428 sub typekey : Local {
429 my ( $self, $c ) = @_;
431 if ( $c->authenticate_typekey) { # uses $c->req and Authen::TypeKey
432 # same stuff as the $c->login method
437 You've now added a new credential verification mechanizm orthogonally to the
438 other components. All you have to do is make sure that the credential verifiers
439 pass on the same types of parameters to the store in order to retrieve user
448 Returns the currently logged in user or undef if there is none.
452 Whether or not a user is logged in right now.
454 The reason this method exists is that C<< $c->user >> may needlessly load the
455 user from the auth store.
457 If you're just going to say
459 if ( $c->user_exists ) {
462 $c->forward("login");
465 it should be more efficient than C<< $c->user >> when a user is marked in the
466 session but C<< $c->user >> hasn't been called yet.
470 Delete the currently logged in user from C<user> and the session.
474 Fetch a particular users details, defined by the given ID, via the default store.
484 Whether or not to store the user's logged in state in the session, if the
485 application is also using the L<Catalyst::Plugin::Session> plugin. This
486 value is set to true per default.
490 If multiple stores are being used, set the module you want as default here.
494 If multiple stores are being used, you need to provide a name for each store
495 here, as a hash, the keys are the names you wish to use, and the values are
496 the the names of the plugins.
499 __PACKAGE__->config( authentication => {
500 store => 'Catalyst::Plugin::Authentication::Store::HtPasswd',
502 'dbic' => 'Catalyst::Plugin::Authentication::Store::DBIC'
508 =head1 METHODS FOR STORE MANAGEMENT
512 =item default_auth_store
514 Return the store whose name is 'default'.
516 This is set to C<< $c->config->{authentication}{store} >> if that value exists,
517 or by using a Store plugin:
519 use Catalyst qw/Authentication Authentication::Store::Minimal/;
521 Sets the default store to
522 L<Catalyst::Plugin::Authentication::Store::Minimal::Backend>.
525 =item get_auth_store $name
527 Return the store whose name is $name.
529 =item get_auth_store_name $store
531 Return the name of the store $store.
535 A hash keyed by name, with the stores registered in the app.
537 =item auth_store_names
539 A ref-hash keyed by store, which contains the names of the stores.
541 =item register_auth_stores %stores_by_name
543 Register stores into the application.
547 =head1 INTERNAL METHODS
551 =item set_authenticated $user
553 Marks a user as authenticated. Should be called from a
554 C<Catalyst::Plugin::Authentication::Credential> plugin after successful
557 This involves setting C<user> and the internal data in C<session> if
558 L<Catalyst::Plugin::Session> is loaded.
560 =item auth_restore_user $user
562 Used to restore a user from the session, by C<user> only when it's actually
565 =item save_user_in_session $user
567 Used to save the user in a session.
571 Revives a user from the session object if there is one.
575 Sets the default configuration parameters.
583 This list might not be up to date.
585 =head2 User Storage Backends
587 L<Catalyst::Plugin::Authentication::Store::Minimal>,
588 L<Catalyst::Plugin::Authentication::Store::Htpasswd>,
589 L<Catalyst::Plugin::Authentication::Store::DBIC> (also works with Class::DBI).
591 =head2 Credential verification
593 L<Catalyst::Plugin::Authentication::Credential::Password>,
594 L<Catalyst::Plugin::Authentication::Credential::HTTP>,
595 L<Catalyst::Plugin::Authentication::Credential::TypeKey>
599 L<Catalyst::Plugin::Authorization::ACL>,
600 L<Catalyst::Plugin::Authorization::Roles>
602 =head2 Internals Documentation
604 L<Catalyst::Plugin::Authentication::Store>
608 L<Catalyst::Plugin::Session>,
609 L<Catalyst::Plugin::Session::PerUser>
611 =head1 DON'T SEE ALSO
613 This module along with its sub plugins deprecate a great number of other
614 modules. These include L<Catalyst::Plugin::Authentication::Simple>,
615 L<Catalyst::Plugin::Authentication::CDBI>.
617 At the time of writing these plugins have not yet been replaced or updated, but
618 should be eventually: L<Catalyst::Plugin::Authentication::OpenID>,
619 L<Catalyst::Plugin::Authentication::LDAP>,
620 L<Catalyst::Plugin::Authentication::CDBI::Basic>,
621 L<Catalyst::Plugin::Authentication::Basic::Remote>.
625 Yuval Kogman, C<nothingmuch@woobling.org>
631 =head1 COPYRIGHT & LICENSE
633 Copyright (c) 2005 the aforementioned authors. All rights
634 reserved. This program is free software; you can redistribute
635 it and/or modify it under the same terms as Perl itself.