1 package Catalyst::Authentication::Realm;
3 use namespace::autoclean;
5 with 'MooseX::Emulate::Class::Accessor::Fast';
6 use String::RewritePrefix;
7 use Try::Tiny qw/ try catch /;
9 __PACKAGE__->mk_accessors(qw/store credential name config/);
11 ## Add use_session config item to realm.
14 my ($class, $realmname, $config, $app) = @_;
16 my $self = { config => $config };
19 $self->name($realmname);
21 if (!exists($self->config->{'use_session'})) {
22 if (exists($app->config->{'Plugin::Authentication'}{'use_session'})) {
23 $self->config->{'use_session'} = $app->config->{'Plugin::Authentication'}{'use_session'};
25 $self->config->{'use_session'} = 1;
29 $app->log->debug("Setting up auth realm $realmname") if $app->debug;
31 # use the Null store as a default - Don't complain if the realm class is being overridden,
32 # as the new realm may behave differently.
33 if( ! exists($config->{store}{class}) ) {
34 $config->{store}{class} = '+Catalyst::Authentication::Store::Null';
35 if (! exists($config->{class})) {
36 $app->log->debug( qq(No Store specified for realm "$realmname", using the Null store.) );
39 my $storeclass = $config->{'store'}{'class'};
41 ## follow catalyst class naming - a + prefix means a fully qualified class, otherwise it's
42 ## taken to mean C::P::A::Store::(specifiedclass)
43 $storeclass = String::RewritePrefix->rewrite({
44 '' => 'Catalyst::Authentication::Store::',
48 # a little niceness - since most systems seem to use the password credential class,
49 # if no credential class is specified we use password.
50 $config->{credential}{class} ||= '+Catalyst::Authentication::Credential::Password';
52 my $credentialclass = $config->{'credential'}{'class'};
54 ## follow catalyst class naming - a + prefix means a fully qualified class, otherwise it's
55 ## taken to mean C::A::Credential::(specifiedclass)
56 $credentialclass = String::RewritePrefix->rewrite({
57 '' => 'Catalyst::Authentication::Credential::',
61 # if we made it here - we have what we need to load the classes
63 ### BACKWARDS COMPATIBILITY - DEPRECATION WARNING:
64 ### we must eval the ensure_class_loaded - because we might need to try the old-style
65 ### ::Plugin:: module naming if the standard method fails.
67 ## Note to self - catch second exception and bitch in detail?
70 Catalyst::Utils::ensure_class_loaded( $credentialclass );
73 # If the file is missing, then try the old-style fallback,
74 # but re-throw anything else for the user to deal with.
75 die $_ unless /^Can't locate/;
76 $app->log->warn( qq(Credential class "$credentialclass" not found, trying deprecated ::Plugin:: style naming. ) );
77 my $origcredentialclass = $credentialclass;
78 $credentialclass =~ s/Catalyst::Authentication/Catalyst::Plugin::Authentication/;
80 try { Catalyst::Utils::ensure_class_loaded( $credentialclass ); }
82 # Likewise this croak is useful if the second exception is also "not found",
83 # but would be confusing if it's anything else.
84 die $_ unless /^Can't locate/;
85 Carp::croak "Unable to load credential class, " . $origcredentialclass . " OR " . $credentialclass .
86 " in realm " . $self->name;
91 Catalyst::Utils::ensure_class_loaded( $storeclass );
94 # If the file is missing, then try the old-style fallback,
95 # but re-throw anything else for the user to deal with.
96 die $_ unless /^Can't locate/;
97 $app->log->warn( qq(Store class "$storeclass" not found, trying deprecated ::Plugin:: style naming. ) );
98 my $origstoreclass = $storeclass;
99 $storeclass =~ s/Catalyst::Authentication/Catalyst::Plugin::Authentication/;
100 try { Catalyst::Utils::ensure_class_loaded( $storeclass ); }
102 # Likewise this croak is useful if the second exception is also "not found",
103 # but would be confusing if it's anything else.
104 die $_ unless /^Can't locate/;
105 Carp::croak "Unable to load store class, " . $origstoreclass . " OR " . $storeclass .
106 " in realm " . $self->name;
110 # BACKWARDS COMPATIBILITY - if the store class does not define find_user, we define it in terms
111 # of get_user and add it to the class. this is because the auth routines use find_user,
112 # and rely on it being present. (this avoids per-call checks)
113 if (!$storeclass->can('find_user')) {
115 *{"${storeclass}::find_user"} = sub {
116 my ($self, $info) = @_;
117 my @rest = @{$info->{rest}} if exists($info->{rest});
118 $self->get_user($info->{id}, @rest);
122 ## a little cruft to stay compatible with some poorly written stores / credentials
123 ## we'll remove this soon.
124 if ($storeclass->can('new')) {
125 $self->store($storeclass->new($config->{'store'}, $app, $self));
128 $app->log->error("THIS IS DEPRECATED: $storeclass has no new() method - Attempting to use uninstantiated");
129 $self->store($storeclass);
131 if ($credentialclass->can('new')) {
132 $self->credential($credentialclass->new($config->{'credential'}, $app, $self));
135 $app->log->error("THIS IS DEPRECATED: $credentialclass has no new() method - Attempting to use uninstantiated");
136 $self->credential($credentialclass);
143 my ( $self, $authinfo, $c ) = @_;
145 my $res = $self->store->find_user($authinfo, $c);
148 if ($self->config->{'auto_create_user'} && $self->store->can('auto_create_user') ) {
149 $res = $self->store->auto_create_user($authinfo, $c);
151 } elsif ($self->config->{'auto_update_user'} && $self->store->can('auto_update_user')) {
152 $res = $self->store->auto_update_user($authinfo, $c, $res);
159 my ($self, $c, $authinfo) = @_;
161 my $user = $self->credential->authenticate($c, $self, $authinfo);
163 $c->set_authenticated($user, $self->name);
170 sub user_is_restorable {
175 and $self->config->{'use_session'}
176 and $c->session_is_valid;
178 return $c->session->{__user};
182 my ($self, $c, $frozen_user) = @_;
184 $frozen_user ||= $self->user_is_restorable($c);
185 return unless defined($frozen_user);
187 my $user = $self->from_session( $c, $frozen_user );
192 # this sets the realm the user originated in.
193 $user->auth_realm($self->name);
196 $self->failed_user_restore($c) ||
197 $c->error("Store claimed to have a restorable user, but restoration failed. Did you change the user's id_field?");
203 ## this occurs if there is a session but the thing the session refers to
204 ## can not be found. Do what you must do here.
205 ## Return true if you can fix the situation and find a user, false otherwise
206 sub failed_user_restore {
209 $self->remove_persisted_user($c);
214 my ($self, $c, $user) = @_;
218 and $self->config->{'use_session'}
219 and $user->supports("session")
221 $c->session->{__user_realm} = $self->name;
223 # we want to ask the store for a user prepared for the session.
224 # but older modules split this functionality between the user and the
225 # store. We try the store first. If not, we use the old method.
226 if ($self->store->can('for_session')) {
227 $c->session->{__user} = $self->store->for_session($c, $user);
229 $c->session->{__user} = $user->for_session;
235 sub remove_persisted_user {
240 and $self->config->{'use_session'}
241 and $c->session_is_valid
243 delete @{ $c->session }{qw/__user __user_realm/};
247 ## backwards compatibility - I don't think many people wrote realms since they
248 ## have only existed for a short time - but just in case.
249 sub save_user_in_session {
250 my ( $self, $c, $user ) = @_;
252 return $self->persist_user($c, $user);
256 my ($self, $c, $frozen_user) = @_;
258 return $self->store->from_session($c, $frozen_user);
270 Catalyst::Authentication::Realm - Base class for realm objects.
280 By default this class is used by
281 L<Catalyst::Plugin::Authentication|Catalyst::Plugin::Authentication> for all
282 realms. The class parameter allows you to choose a different class to use for
283 this realm. Creating a new Realm class can allow for authentication methods
284 that fall outside the normal credential/store methodology.
286 =item auto_create_user
288 Set this to true if you wish this realm to auto-create user accounts when the
289 user doesn't exist (most useful for remote authentication schemes).
291 =item auto_update_user
293 Set this to true if you wish this realm to auto-update user accounts after
294 authentication (most useful for remote authentication schemes).
298 Sets session usage for this particular realm - overriding the global use_sesion setting.
305 =head2 new( $realmname, $config, $app )
307 Instantiantes this realm, plus the specified store and credential classes.
311 Returns an instance of the store object for this realm.
315 Returns an instance of the credential object for this realm.
317 =head2 find_user( $authinfo, $c )
319 Retrieves the user given the authentication information provided. This
320 is most often called from the credential. The default realm class simply
321 delegates this call the store object. If enabled, auto-creation and
322 auto-updating of users is also handled here.
324 =head2 authenticate( $c, $authinfo)
326 Performs the authentication process for the current realm. The default
327 realm class simply delegates this to the credential and sets
328 the authenticated user on success. Returns the authenticated user object;
330 =head1 USER PERSISTENCE
332 The Realm class allows complete control over the persistance of users
333 between requests. By default the realm attempts to use the Catalyst
334 session system to accomplish this. By overriding the methods below
335 in a custom Realm class, however, you can handle user persistance in
338 =head2 persist_user($c, $user)
340 persist_user is the entry point for saving user information between requests
341 in most cases this will utilize the session. By default this uses the
342 catalyst session system to store the user by calling for_session on the
343 active store. The user object must be a subclass of
344 Catalyst::Authentication::User. If you have updated the user object, you
345 must call persist_user again to ensure that the persisted user object reflects
348 =head2 remove_persisted_user($c)
350 Removes any persisted user data. By default, removes the user from the session.
352 =head2 user_is_restorable( $c )
354 Returns whether there is a persisted user that may be restored. Returns
355 a token used to restore the user. With the default session persistance
356 it returns the raw frozen user information.
358 =head2 restore_user($c, [$frozen_user])
360 Restores the user from the given frozen_user parameter, or if not provided,
361 using the response from $self->user_is_restorable(); Uses $self->from_session()
362 to decode the frozen user.
364 =head2 failed_user_restore($c)
366 If there is a session to restore, but the restore fails for any reason then this method
367 is called. This method supplied just removes the persisted user, but can be overridden
368 if required to have more complex logic (e.g. finding a the user by their 'old' username).
370 =head2 from_session($c, $frozenuser )
372 Decodes the frozenuser information provided and returns an instantiated
373 user object. By default, this call is delegated to $store->from_session().
375 =head2 save_user_in_session($c, $user)
377 DEPRECATED. Use persist_user instead. (this simply calls persist_user)