lib/Catalyst/Authentication/Realm.pm

   1 package Catalyst::Authentication::Realm;
   2
   3 use strict;
   4 use warnings;
   5
   6 use base qw/Class::Accessor::Fast/;
   7
   8 BEGIN {
   9     __PACKAGE__->mk_accessors(qw/store credential name config/);
  10 };
  11
  12 ## Add use_session config item to realm.
  13
  14 sub new {
  15     my ($class, $realmname, $config, $app) = @_;
  16
  17     my $self = { config => $config };
  18     bless $self, $class;
  19
  20     $self->name($realmname);
  21
  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'};
  25         } else {
  26             $self->config->{'use_session'} = 1;
  27         }
  28     }
  29
  30     $app->log->debug("Setting up auth realm $realmname") if $app->debug;
  31
  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.) );
  36     }
  37     my $storeclass = $config->{'store'}{'class'};
  38
  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}";
  43     } else {
  44         $storeclass = $1;
  45     }
  46
  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';
  50
  51     my $credentialclass = $config->{'credential'}{'class'};
  52
  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}";
  57     } else {
  58         $credentialclass = $1;
  59     }
  60
  61     # if we made it here - we have what we need to load the classes
  62
  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.
  66
  67     ## Note to self - catch second exception and bitch in detail?
  68
  69     eval {
  70         Catalyst::Utils::ensure_class_loaded( $credentialclass );
  71     };
  72
  73     if ($@) {
  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/;
  77
  78         eval { Catalyst::Utils::ensure_class_loaded( $credentialclass ); };
  79         if ($@) {
  80             Carp::croak "Unable to load credential class, " . $origcredentialclass . " OR " . $credentialclass .
  81                         " in realm " . $self->name;
  82         }
  83     }
  84
  85     eval {
  86         Catalyst::Utils::ensure_class_loaded( $storeclass );
  87     };
  88
  89     if ($@) {
  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 ); };
  94         if ($@) {
  95             Carp::croak "Unable to load store class, " . $origstoreclass . " OR " . $storeclass .
  96                         " in realm " . $self->name;
  97         }
  98     }
  99
 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')) {
 104         no strict 'refs';
 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);
 109                                             };
 110     }
 111
 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));
 116     } else {
 117         $app->log->error("THIS IS DEPRECATED: $storeclass has no new() method - Attempting to use uninstantiated");
 118         $self->store($storeclass);
 119     }
 120     if ($credentialclass->can('new')) {
 121         $self->credential($credentialclass->new($config->{'credential'}, $app, $self));
 122     } else {
 123         $app->log->error("THIS IS DEPRECATED: $credentialclass has no new() method - Attempting to use uninstantiated");
 124         $self->credential($credentialclass);
 125     }
 126
 127     return $self;
 128 }
 129
 130 sub find_user {
 131     my ( $self, $authinfo, $c ) = @_;
 132
 133     my $res = $self->store->find_user($authinfo, $c);
 134
 135     if (!$res) {
 136       if ($self->config->{'auto_create_user'} && $self->store->can('auto_create_user') ) {
 137           $res = $self->store->auto_create_user($authinfo, $c);
 138       }
 139     } elsif ($self->config->{'auto_update_user'} && $self->store->can('auto_update_user')) {
 140         $res = $self->store->auto_update_user($authinfo, $c, $res);
 141     }
 142
 143     return $res;
 144 }
 145
 146 sub authenticate {
 147      my ($self, $c, $authinfo) = @_;
 148
 149      my $user = $self->credential->authenticate($c, $self, $authinfo);
 150      if (ref($user)) {
 151          $c->set_authenticated($user, $self->name);
 152          return $user;
 153      } else {
 154          return undef;
 155      }
 156 }
 157
 158 sub user_is_restorable {
 159     my ($self, $c) = @_;
 160
 161     return unless
 162          $c->isa("Catalyst::Plugin::Session")
 163          and $self->config->{'use_session'}
 164          and $c->session_is_valid;
 165
 166     return $c->session->{__user};
 167 }
 168
 169 sub restore_user {
 170     my ($self, $c, $frozen_user) = @_;
 171
 172     $frozen_user ||= $self->user_is_restorable($c);
 173     return unless defined($frozen_user);
 174
 175     my $user = $self->from_session( $c, $frozen_user );
 176
 177     if ($user) {
 178         $c->_user( $user );
 179
 180         # this sets the realm the user originated in.
 181         $user->auth_realm($self->name);
 182     } else {
 183                 Catalyst::Exception->throw("Store claimed to have a restorable user, but restoration failed.  Did you change the user's id_field?");
 184         }
 185
 186     return $user;
 187 }
 188
 189 sub persist_user {
 190     my ($self, $c, $user) = @_;
 191
 192     if (
 193         $c->isa("Catalyst::Plugin::Session")
 194         and $self->config->{'use_session'}
 195         and $user->supports("session")
 196     ) {
 197         $c->session->{__user_realm} = $self->name;
 198
 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);
 204         } else {
 205             $c->session->{__user} = $user->for_session;
 206         }
 207     }
 208     return $user;
 209 }
 210
 211 sub remove_persisted_user {
 212     my ($self, $c) = @_;
 213
 214     if (
 215         $c->isa("Catalyst::Plugin::Session")
 216         and $self->config->{'use_session'}
 217         and $c->session_is_valid
 218     ) {
 219         delete @{ $c->session }{qw/__user __user_realm/};
 220     }
 221 }
 222
 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 ) = @_;
 227
 228     return $self->persist_user($c, $user);
 229 }
 230
 231 sub from_session {
 232     my ($self, $c, $frozen_user) = @_;
 233
 234     return $self->store->from_session($c, $frozen_user);
 235 }
 236
 237
 238 __PACKAGE__;
 239
 240 __END__
 241
 242 =pod
 243
 244 =head1 NAME
 245
 246 Catalyst::Authentication::Realm - Base class for realm objects.
 247
 248 =head1 DESCRIPTION
 249
 250 =head1 CONFIGURATION
 251
 252 =over 4
 253
 254 =item class
 255
 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.
 261
 262 =item auto_create_user
 263
 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).
 266
 267 =item auto_update_user
 268
 269 Set this to true if you wish this realm to auto-update user accounts after
 270 authentication (most useful for remote authentication schemes).
 271
 272 =item use_session
 273
 274 Sets session usage for this particular realm - overriding the global use_sesion setting.
 275
 276
 277 =back
 278
 279 =head1 METHODS
 280
 281 =head2 new( $realmname, $config, $app )
 282
 283 Instantiantes this realm, plus the specified store and credential classes.
 284
 285 =head2 store( )
 286
 287 Returns an instance of the store object for this realm.
 288
 289 =head2 credential( )
 290
 291 Returns an instance of the credential object for this realm.
 292
 293 =head2 find_user( $authinfo, $c )
 294
 295 Retrieves the user given the authentication information provided.  This
 296 is most often called from the credential.  The default realm class simply
 297 delegates this call the store object.  If enabled, auto-creation and
 298 auto-updating of users is also handled here.
 299
 300 =head2 authenticate( $c, $authinfo)
 301
 302 Performs the authentication process for the current realm.  The default
 303 realm class simply delegates this to the credential and sets
 304 the authenticated user on success.  Returns the authenticated user object;
 305
 306 =head1 USER PERSISTENCE
 307
 308 The Realm class allows complete control over the persistance of users
 309 between requests.  By default the realm attempts to use the Catalyst
 310 session system to accomplish this.  By overriding the methods below
 311 in a custom Realm class, however, you can handle user persistance in
 312 any way you see fit.
 313
 314 =head2 persist_user($c, $user)
 315
 316 persist_user is the entry point for saving user information between requests
 317 in most cases this will utilize the session.  By default this uses the
 318 catalyst session system to store the user by calling for_session on the
 319 active store.  The user object must be a subclass of
 320 Catalyst::Authentication::User.  If you have updated the user object, you
 321 must call persist_user again to ensure that the persisted user object reflects
 322 your updates.
 323
 324 =head2 remove_persisted_user($c)
 325
 326 Removes any persisted user data.  By default, removes the user from the session.
 327
 328 =head2 user_is_restorable( $c )
 329
 330 Returns whether there is a persisted user that may be restored.  Returns
 331 a token used to restore the user.  With the default session persistance
 332 it returns the raw frozen user information.
 333
 334 =head2 restore_user($c, [$frozen_user])
 335
 336 Restores the user from the given frozen_user parameter, or if not provided,
 337 using the response from $self->user_is_restorable();  Uses $self->from_session()
 338 to decode the frozen user.
 339
 340
 341 =head2 from_session($c, $frozenuser )
 342
 343 Decodes the frozenuser information provided and returns an instantiated
 344 user object.  By default, this call is delegated to $store->from_session().
 345
 346 =head2 save_user_in_session($c, $user)
 347
 348 DEPRECATED.  Use persist_user instead.  (this simply calls persist_user)
 349
 350 =cut