1 package Catalyst::Authentication::Realm;
6 use base qw/Class::Accessor::Fast/;
9 __PACKAGE__->mk_accessors(qw/store credential name config/);
12 ## Add use_session config item to realm.
15 my ($class, $realmname, $config, $app) = @_;
17 my $self = { config => $config };
20 $self->name($realmname);
22 if (!exists($self->config->{'use_session'})) {
23 if (exists($app->config->{'Plugin::Authentication'}{'use_session'})) {
24 $self->config->{'use_session'} = $app->config->{'Plugin::Authentication'}{'use_session'};
26 $self->config->{'use_session'} = 1;
30 $app->log->debug("Setting up auth realm $realmname") if $app->debug;
32 # use the Null store as a default
33 if( ! exists $config->{store}{class} ) {
34 $config->{store}{class} = '+Catalyst::Authentication::Store::Null';
35 $app->log->debug( qq(No Store specified for realm "$realmname", using the Null store.) );
37 my $storeclass = $config->{'store'}{'class'};
39 ## follow catalyst class naming - a + prefix means a fully qualified class, otherwise it's
40 ## taken to mean C::P::A::Store::(specifiedclass)
41 if ($storeclass !~ /^\+(.*)$/ ) {
42 $storeclass = "Catalyst::Authentication::Store::${storeclass}";
47 # a little niceness - since most systems seem to use the password credential class,
48 # if no credential class is specified we use password.
49 $config->{credential}{class} ||= '+Catalyst::Authentication::Credential::Password';
51 my $credentialclass = $config->{'credential'}{'class'};
53 ## follow catalyst class naming - a + prefix means a fully qualified class, otherwise it's
54 ## taken to mean C::A::Credential::(specifiedclass)
55 if ($credentialclass !~ /^\+(.*)$/ ) {
56 $credentialclass = "Catalyst::Authentication::Credential::${credentialclass}";
58 $credentialclass = $1;
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 );
74 $app->log->warn( qq(Credential class "$credentialclass" not found, trying deprecated ::Plugin:: style naming. ) );
75 my $origcredentialclass = $credentialclass;
76 $credentialclass =~ s/Catalyst::Authentication/Catalyst::Plugin::Authentication/;
78 eval { Catalyst::Utils::ensure_class_loaded( $credentialclass ); };
80 Carp::croak "Unable to load credential class, " . $origcredentialclass . " OR " . $credentialclass .
81 " in realm " . $self->name;
86 Catalyst::Utils::ensure_class_loaded( $storeclass );
90 $app->log->warn( qq(Store class "$storeclass" not found, trying deprecated ::Plugin:: style naming. ) );
91 my $origstoreclass = $storeclass;
92 $storeclass =~ s/Catalyst::Authentication/Catalyst::Plugin::Authentication/;
93 eval { Catalyst::Utils::ensure_class_loaded( $storeclass ); };
95 Carp::croak "Unable to load store class, " . $origstoreclass . " OR " . $storeclass .
96 " in realm " . $self->name;
100 # BACKWARDS COMPATIBILITY - if the store class does not define find_user, we define it in terms
101 # of get_user and add it to the class. this is because the auth routines use find_user,
102 # and rely on it being present. (this avoids per-call checks)
103 if (!$storeclass->can('find_user')) {
105 *{"${storeclass}::find_user"} = sub {
106 my ($self, $info) = @_;
107 my @rest = @{$info->{rest}} if exists($info->{rest});
108 $self->get_user($info->{id}, @rest);
112 ## a little cruft to stay compatible with some poorly written stores / credentials
113 ## we'll remove this soon.
114 if ($storeclass->can('new')) {
115 $self->store($storeclass->new($config->{'store'}, $app, $self));
117 $app->log->error("THIS IS DEPRECATED: $storeclass has no new() method - Attempting to use uninstantiated");
118 $self->store($storeclass);
120 if ($credentialclass->can('new')) {
121 $self->credential($credentialclass->new($config->{'credential'}, $app, $self));
123 $app->log->error("THIS IS DEPRECATED: $credentialclass has no new() method - Attempting to use uninstantiated");
124 $self->credential($credentialclass);
131 my ( $self, $authinfo, $c ) = @_;
133 my $res = $self->store->find_user($authinfo, $c);
136 if ($self->config->{'auto_create_user'} && $self->store->can('auto_create_user') ) {
137 $res = $self->store->auto_create_user($authinfo, $c);
139 } elsif ($self->config->{'auto_update_user'} && $self->store->can('auto_update_user')) {
140 $res = $self->store->auto_update_user($authinfo, $c, $res);
147 my ($self, $c, $authinfo) = @_;
149 my $user = $self->credential->authenticate($c, $self, $authinfo);
151 $c->set_authenticated($user, $self->name);
158 sub user_is_restorable {
162 $c->isa("Catalyst::Plugin::Session")
163 and $self->config->{'use_session'}
164 and $c->session_is_valid;
166 return $c->session->{__user};
170 my ($self, $c, $frozen_user) = @_;
172 $frozen_user ||= $self->user_is_restorable($c);
173 return unless defined($frozen_user);
175 my $user = $self->from_session( $c, $frozen_user );
180 # this sets the realm the user originated in.
181 $user->auth_realm($self->name);
183 Catalyst::Exception->throw("Store claimed to have a restorable user, but restoration failed. Did you change the user's id_field?");
190 my ($self, $c, $user) = @_;
193 $c->isa("Catalyst::Plugin::Session")
194 and $self->config->{'use_session'}
195 and $user->supports("session")
197 $c->session->{__user_realm} = $self->name;
199 # we want to ask the store for a user prepared for the session.
200 # but older modules split this functionality between the user and the
201 # store. We try the store first. If not, we use the old method.
202 if ($self->store->can('for_session')) {
203 $c->session->{__user} = $self->store->for_session($c, $user);
205 $c->session->{__user} = $user->for_session;
211 sub remove_persisted_user {
215 $c->isa("Catalyst::Plugin::Session")
216 and $self->config->{'use_session'}
217 and $c->session_is_valid
219 delete @{ $c->session }{qw/__user __user_realm/};
223 ## backwards compatibility - I don't think many people wrote realms since they
224 ## have only existed for a short time - but just in case.
225 sub save_user_in_session {
226 my ( $self, $c, $user ) = @_;
228 return $self->persist_user($c, $user);
232 my ($self, $c, $frozen_user) = @_;
234 return $self->store->from_session($c, $frozen_user);
246 Catalyst::Authentication::Realm - Base class for realm objects.
256 By default this class is used by
257 L<Catalyst::Plugin::Authentication|Catalyst::Plugin::Authentication> for all
258 realms. The class parameter allows you to choose a different class to use for
259 this realm. Creating a new Realm class can allow for authentication methods
260 that fall outside the normal credential/store methodology.
262 =item auto_create_user
264 Set this to true if you wish this realm to auto-create user accounts when the
265 user doesn't exist (most useful for remote authentication schemes).
267 =item auto_update_user
269 Set this to true if you wish this realm to auto-update user accounts after
270 authentication (most useful for remote authentication schemes).
276 =head2 new( $realmname, $config, $app )
278 Instantiantes this realm, plus the specified store and credential classes.
282 Returns an instance of the store object for this realm.
286 Returns an instance of the credential object for this realm.
288 =head2 find_user( $authinfo, $c )
290 Retrieves the user given the authentication information provided. This
291 is most often called from the credential. The default realm class simply
292 delegates this call the store object. If enabled, auto-creation and
293 auto-updating of users is also handled here.
295 =head2 authenticate( $c, $authinfo)
297 Performs the authentication process for the current realm. The default
298 realm class simply delegates this to the credential and sets
299 the authenticated user on success. Returns the authenticated user object;
301 =head2 save_user_in_session($c, $user)
303 Used to save the user in a session. Saves $user in the current session,
304 marked as originating in the current realm. Calls $store->for_session() by
305 default. If for_session is not available in the store class, will attempt
306 to call $user->for_session().
308 =head2 persist_user($c, $user)
310 Takes the user data and persists it in the sessi.on
312 =head2 remove_persisted_user($c)
314 Removes any persisted user data in the session.
316 =head2 restore_user($c, [$frozen_user])
318 Restores the user from parameter, or the session by default.
320 =head2 user_is_restorable( $c )
322 Predicate to tell you if the current session has restorable user data.
324 =head2 from_session($c, $frozenuser )
326 Triggers restoring of the user from data in the session. The default realm
327 class simply delegates the call to $store->from_session($c, $frozenuser);