1 package Catalyst::Authentication::Realm;
6 use base qw/Class::Accessor::Fast/;
9 __PACKAGE__->mk_accessors(qw/store credential name config/);
13 my ($class, $realmname, $config, $app) = @_;
15 my $self = { config => $config };
18 $self->name($realmname);
20 $app->log->debug("Setting up auth realm $realmname") if $app->debug;
22 # use the Null store as a default
23 if( ! exists $config->{store}{class} ) {
24 $config->{store}{class} = '+Catalyst::Authentication::Store::Null';
25 $app->log->debug( qq(No Store specified for realm "$realmname", using the Null store.) );
27 my $storeclass = $config->{'store'}{'class'};
29 ## follow catalyst class naming - a + prefix means a fully qualified class, otherwise it's
30 ## taken to mean C::P::A::Store::(specifiedclass)
31 if ($storeclass !~ /^\+(.*)$/ ) {
32 $storeclass = "Catalyst::Authentication::Store::${storeclass}";
37 # a little niceness - since most systems seem to use the password credential class,
38 # if no credential class is specified we use password.
39 $config->{credential}{class} ||= '+Catalyst::Authentication::Credential::Password';
41 my $credentialclass = $config->{'credential'}{'class'};
43 ## follow catalyst class naming - a + prefix means a fully qualified class, otherwise it's
44 ## taken to mean C::A::Credential::(specifiedclass)
45 if ($credentialclass !~ /^\+(.*)$/ ) {
46 $credentialclass = "Catalyst::Authentication::Credential::${credentialclass}";
48 $credentialclass = $1;
51 # if we made it here - we have what we need to load the classes
53 ### BACKWARDS COMPATIBILITY - DEPRECATION WARNING:
54 ### we must eval the ensure_class_loaded - because we might need to try the old-style
55 ### ::Plugin:: module naming if the standard method fails.
57 ## Note to self - catch second exception and bitch in detail?
60 Catalyst::Utils::ensure_class_loaded( $credentialclass );
64 $app->log->warn( qq(Credential class "$credentialclass" not found, trying deprecated ::Plugin:: style naming. ) );
65 my $origcredentialclass = $credentialclass;
66 $credentialclass =~ s/Catalyst::Authentication/Catalyst::Plugin::Authentication/;
68 eval { Catalyst::Utils::ensure_class_loaded( $credentialclass ); };
70 Carp::croak "Unable to load credential class, " . $origcredentialclass . " OR " . $credentialclass .
71 " in realm " . $self->name;
76 Catalyst::Utils::ensure_class_loaded( $storeclass );
80 $app->log->warn( qq(Store class "$storeclass" not found, trying deprecated ::Plugin:: style naming. ) );
81 my $origstoreclass = $storeclass;
82 $storeclass =~ s/Catalyst::Authentication/Catalyst::Plugin::Authentication/;
83 eval { Catalyst::Utils::ensure_class_loaded( $storeclass ); };
85 Carp::croak "Unable to load store class, " . $origstoreclass . " OR " . $storeclass .
86 " in realm " . $self->name;
90 # BACKWARDS COMPATIBILITY - if the store class does not define find_user, we define it in terms
91 # of get_user and add it to the class. this is because the auth routines use find_user,
92 # and rely on it being present. (this avoids per-call checks)
93 if (!$storeclass->can('find_user')) {
95 *{"${storeclass}::find_user"} = sub {
96 my ($self, $info) = @_;
97 my @rest = @{$info->{rest}} if exists($info->{rest});
98 $self->get_user($info->{id}, @rest);
102 ## a little cruft to stay compatible with some poorly written stores / credentials
103 ## we'll remove this soon.
104 if ($storeclass->can('new')) {
105 $self->store($storeclass->new($config->{'store'}, $app, $self));
107 $app->log->error("THIS IS DEPRECATED: $storeclass has no new() method - Attempting to use uninstantiated");
108 $self->store($storeclass);
110 if ($credentialclass->can('new')) {
111 $self->credential($credentialclass->new($config->{'credential'}, $app, $self));
113 $app->log->error("THIS IS DEPRECATED: $credentialclass has no new() method - Attempting to use uninstantiated");
114 $self->credential($credentialclass);
121 my ( $self, $authinfo, $c ) = @_;
123 my $res = $self->store->find_user($authinfo, $c);
126 if ($self->config->{'auto_create_user'} && $self->store->can('auto_create_user') ) {
127 $res = $self->store->auto_create_user($authinfo, $c);
129 } elsif ($self->config->{'auto_update_user'} && $self->store->can('auto_update_user')) {
130 $res = $self->store->auto_update_user($authinfo, $c, $res);
137 my ($self, $c, $authinfo) = @_;
139 my $user = $self->credential->authenticate($c, $self, $authinfo);
141 $c->set_authenticated($user, $self->name);
148 sub user_is_restorable {
152 $c->isa("Catalyst::Plugin::Session")
153 and $c->config->{'Plugin::Authentication'}{'use_session'}
154 and $c->session_is_valid;
156 return $c->session->{__user};
160 my ($self, $c, $frozen_user) = @_;
162 $frozen_user ||= $self->user_is_restorable($c);
163 return unless defined($frozen_user);
165 $c->_user( my $user = $self->from_session( $c, $frozen_user ) );
167 # this sets the realm the user originated in.
168 $user->auth_realm($self->name);
174 my ($self, $c, $user) = @_;
177 $c->isa("Catalyst::Plugin::Session")
178 and $c->config->{'Plugin::Authentication'}{'use_session'}
179 and $user->supports("session")
181 $c->session->{__user_realm} = $self->name;
183 # we want to ask the store for a user prepared for the session.
184 # but older modules split this functionality between the user and the
185 # store. We try the store first. If not, we use the old method.
186 if ($self->store->can('for_session')) {
187 $c->session->{__user} = $self->store->for_session($c, $user);
189 $c->session->{__user} = $user->for_session;
195 sub remove_persisted_user {
199 $c->isa("Catalyst::Plugin::Session")
200 and $c->config->{'Plugin::Authentication'}{'use_session'}
201 and $c->session_is_valid
203 delete @{ $c->session }{qw/__user __user_realm/};
207 ## backwards compatibility - I don't think many people wrote realms since they
208 ## have only existed for a short time - but just in case.
209 sub save_user_in_session {
210 my ( $self, $c, $user ) = @_;
212 return $self->persist_user($c, $user);
216 my ($self, $c, $frozen_user) = @_;
218 return $self->store->from_session($c, $frozen_user);
230 Catalyst::Authentication::Realm - Base class for realm objects.
240 By default this class is used by
241 L<Catalyst::Plugin::Authentication|Catalyst::Plugin::Authentication> for all
242 realms. The class parameter allows you to choose a different class to use for
243 this realm. Creating a new Realm class can allow for authentication methods
244 that fall outside the normal credential/store methodology.
246 =item auto_create_user
248 Set this to true if you wish this realm to auto-create user accounts when the
249 user doesn't exist (most useful for remote authentication schemes).
251 =item auto_update_user
253 Set this to true if you wish this realm to auto-update user accounts after
254 authentication (most useful for remote authentication schemes).
260 =head2 new( $realmname, $config, $app )
262 Instantiantes this realm, plus the specified store and credential classes.
266 Returns an instance of the store object for this realm.
270 Returns an instance of the credential object for this realm.
272 =head2 find_user( $authinfo, $c )
274 Retrieves the user given the authentication information provided. This
275 is most often called from the credential. The default realm class simply
276 delegates this call the store object. If enabled, auto-creation and
277 auto-updating of users is also handled here.
279 =head2 authenticate( $c, $authinfo)
281 Performs the authentication process for the current realm. The default
282 realm class simply delegates this to the credential and sets
283 the authenticated user on success. Returns the authenticated user object;
285 =head save_user_in_session($c, $user)
287 Used to save the user in a session. Saves $user in the current session,
288 marked as originating in the current realm. Calls $store->for_session() by
289 default. If for_session is not available in the store class, will attempt
290 to call $user->for_session().
292 =head2 from_session($c, $frozenuser )
294 Triggers restoring of the user from data in the session. The default realm
295 class simply delegates the call to $store->from_session($c, $frozenuser);