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/;
20 # constant->import(have_want => eval { require Want });
23 our $VERSION = "0.02";
25 sub set_authenticated {
26 my ( $c, $user ) = @_;
29 $c->request->{user} = $user; # compatibility kludge
31 if ( $c->isa("Catalyst::Plugin::Session")
32 and $c->config->{authentication}{use_session}
33 and $user->supports("session") )
35 $c->save_user_in_session($user);
38 $c->NEXT::set_authenticated($user);
50 if ( $user and !Scalar::Util::blessed($user) ) {
51 # return 1 if have_want() && Want::want("BOOL");
52 return $c->auth_restore_user($user);
60 return defined($c->_user);
63 sub save_user_in_session {
64 my ( $c, $user ) = @_;
66 my $store = $user->store || ref $user;
67 $c->session->{__user_store} = $c->get_auth_store_name($store) || $store;
68 $c->session->{__user} = $user->for_session;
76 if ( $c->isa("Catalyst::Plugin::Session")
77 and $c->config->{authentication}{use_session} )
79 delete @{ $c->session }{qw/__user __user_store/};
86 if ( my $store = $c->default_auth_store ) {
87 return $store->get_user($uid);
90 Catalyst::Exception->throw(
91 "The user id $uid was passed to an authentication "
92 . "plugin, but no default store was specified" );
97 my $c = shift->NEXT::prepare(@_);
99 if ( $c->isa("Catalyst::Plugin::Session")
102 if ( $c->sessionid and my $frozen_user = $c->session->{__user} ) {
103 $c->_user($frozen_user);
110 sub auth_restore_user {
111 my ( $c, $frozen_user, $store_name ) = @_;
114 unless $c->isa("Catalyst::Plugin::Session")
115 and $c->config->{authentication}{use_session}
118 $store_name ||= $c->session->{__user_store};
119 $frozen_user ||= $c->session->{__user};
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 for both authentication (checking the user is who they claim to be), and 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 store the user information, and can store any amount of data related to the user. Multiple stores can be accessed from within one application. Credentials are used to verify users, using the store, given data from the frontend.
221 To implement authentication in a catalyst application you need to add this module, plus at least one store and one credential module.
223 Authentication data can also be stored in a session, if the application is using the L<Catalyst::Plugin::Session> module.
231 Returns the currently logged in user or undef if there is none.
235 Whether or not a user is logged in right now.
237 The reason this method exists is that C<<$c->user>> may needlessly load the
238 user from the auth store.
240 If you're just going to say
242 if ( $c->user_user ) {
245 $c->forward("login");
248 it should be more efficient than C<<$c->user>> when a user is marked in the session
249 but C<<$c->user>> hasn't been called yet.
253 Delete the currently logged in user from C<user> and the session.
257 Fetch a particular users details, defined by the given ID, via the default store.
267 Whether or not to store the user's logged in state in the session, if the
268 application is also using the L<Catalyst::Plugin::Session> plugin.
272 =head1 METHODS FOR STORE MANAGEMENT
276 =item default_auth_store
278 Return the store whose name is 'default'.
280 This is set to C<< $c->config->{authentication}{store} >> if that value exists,
281 or by using a Store plugin:
283 use Catalyst qw/Authentication Authentication::Store::Minimal/;
285 Sets the default store to
286 L<Catalyst::Plugin::Authentication::Store::Minimal::Backend>.
289 =item get_auth_store $name
291 Return the store whose name is $name.
293 =item get_auth_store_name $store
295 Return the name of the store $store.
299 A hash keyed by name, with the stores registered in the app.
301 =item auth_store_names
303 A ref-hash keyed by store, which contains the names of the stores.
305 =item register_auth_stores %stores_by_name
307 Register stores into the application.
311 =head1 INTERNAL METHODS
315 =item set_authenticated $user
317 Marks a user as authenticated. Should be called from a
318 C<Catalyst::Plugin::Authentication::Credential> plugin after successful
321 This involves setting C<user> and the internal data in C<session> if
322 L<Catalyst::Plugin::Session> is loaded.
324 =item auth_restore_user $user
326 Used to restore a user from the session, by C<user> only when it's actually
329 =item save_user_in_session $user
331 Used to save the user in a session.
335 Revives a user from the session object if there is one.
339 Sets the default configuration parameters.
347 L<Catalyst::Plugin::Authentication::Credential::Password>,
348 L<Catalyst::Plugin::Authentication::Store::Minimal>,
349 L<Catalyst::Plugin::Authorization::ACL>,
350 L<Catalyst::Plugin::Authorization::Roles>.
354 Yuval Kogman, C<nothingmuch@woobling.org>
356 =head1 COPYRIGHT & LICNESE
358 Copyright (c) 2005 the aforementioned authors. All rights
359 reserved. This program is free software; you can redistribute
360 it and/or modify it under the same terms as Perl itself.