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         # If the file is missing, then try the old-style fallback,
  75         # but re-throw anything else for the user to deal with.
  76         die unless $@ =~ /^Can't locate/;
  77         $app->log->warn( qq(Credential class "$credentialclass" not found, trying deprecated ::Plugin:: style naming. ) );
  78         my $origcredentialclass = $credentialclass;
  79         $credentialclass =~ s/Catalyst::Authentication/Catalyst::Plugin::Authentication/;
  80
  81         eval { Catalyst::Utils::ensure_class_loaded( $credentialclass ); };
  82         if ($@) {
  83             # Likewise this croak is useful if the second exception is also "not found",
  84             # but would be confusing if it's anything else.
  85             die unless $@ =~ /^Can't locate/;
  86             Carp::croak "Unable to load credential class, " . $origcredentialclass . " OR " . $credentialclass .
  87                         " in realm " . $self->name;
  88         }
  89     }
  90
  91     eval {
  92         Catalyst::Utils::ensure_class_loaded( $storeclass );
  93     };
  94
  95     if ($@) {
  96         # If the file is missing, then try the old-style fallback,
  97         # but re-throw anything else for the user to deal with.
  98         die unless $@ =~ /^Can't locate/;
  99         $app->log->warn( qq(Store class "$storeclass" not found, trying deprecated ::Plugin:: style naming. ) );
 100         my $origstoreclass = $storeclass;
 101         $storeclass =~ s/Catalyst::Authentication/Catalyst::Plugin::Authentication/;
 102         eval { Catalyst::Utils::ensure_class_loaded( $storeclass ); };
 103         if ($@) {
 104             # Likewise this croak is useful if the second exception is also "not found",
 105             # but would be confusing if it's anything else.
 106             die unless $@ =~ /^Can't locate/;
 107             Carp::croak "Unable to load store class, " . $origstoreclass . " OR " . $storeclass .
 108                         " in realm " . $self->name;
 109         }
 110     }
 111
 112     # BACKWARDS COMPATIBILITY - if the store class does not define find_user, we define it in terms
 113     # of get_user and add it to the class.  this is because the auth routines use find_user,
 114     # and rely on it being present. (this avoids per-call checks)
 115     if (!$storeclass->can('find_user')) {
 116         no strict 'refs';
 117         *{"${storeclass}::find_user"} = sub {
 118                                                 my ($self, $info) = @_;
 119                                                 my @rest = @{$info->{rest}} if exists($info->{rest});
 120                                                 $self->get_user($info->{id}, @rest);
 121                                             };
 122     }
 123
 124     ## a little cruft to stay compatible with some poorly written stores / credentials
 125     ## we'll remove this soon.
 126     if ($storeclass->can('new')) {
 127         $self->store($storeclass->new($config->{'store'}, $app, $self));
 128     } else {
 129         $app->log->error("THIS IS DEPRECATED: $storeclass has no new() method - Attempting to use uninstantiated");
 130         $self->store($storeclass);
 131     }
 132     if ($credentialclass->can('new')) {
 133         $self->credential($credentialclass->new($config->{'credential'}, $app, $self));
 134     } else {
 135         $app->log->error("THIS IS DEPRECATED: $credentialclass has no new() method - Attempting to use uninstantiated");
 136         $self->credential($credentialclass);
 137     }
 138
 139     return $self;
 140 }
 141
 142 sub find_user {
 143     my ( $self, $authinfo, $c ) = @_;
 144
 145     my $res = $self->store->find_user($authinfo, $c);
 146
 147     if (!$res) {
 148       if ($self->config->{'auto_create_user'} && $self->store->can('auto_create_user') ) {
 149           $res = $self->store->auto_create_user($authinfo, $c);
 150       }
 151     } elsif ($self->config->{'auto_update_user'} && $self->store->can('auto_update_user')) {
 152         $res = $self->store->auto_update_user($authinfo, $c, $res);
 153     }
 154
 155     return $res;
 156 }
 157
 158 sub authenticate {
 159      my ($self, $c, $authinfo) = @_;
 160
 161      my $user = $self->credential->authenticate($c, $self, $authinfo);
 162      if (ref($user)) {
 163          $c->set_authenticated($user, $self->name);
 164          return $user;
 165      } else {
 166          return undef;
 167      }
 168 }
 169
 170 sub user_is_restorable {
 171     my ($self, $c) = @_;
 172
 173     return unless
 174          $c->isa("Catalyst::Plugin::Session")
 175          and $self->config->{'use_session'}
 176          and $c->session_is_valid;
 177
 178     return $c->session->{__user};
 179 }
 180
 181 sub restore_user {
 182     my ($self, $c, $frozen_user) = @_;
 183
 184     $frozen_user ||= $self->user_is_restorable($c);
 185     return unless defined($frozen_user);
 186
 187     my $user = $self->from_session( $c, $frozen_user );
 188
 189     if ($user) {
 190         $c->_user( $user );
 191
 192         # this sets the realm the user originated in.
 193         $user->auth_realm($self->name);
 194     }
 195     else {
 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?");
 198         }
 199
 200     return $user;
 201 }
 202
 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 {
 207         my ($self, $c) = @_;
 208
 209         $self->remove_persisted_user($c);
 210         return;
 211 }
 212
 213 sub persist_user {
 214     my ($self, $c, $user) = @_;
 215
 216     if (
 217         $c->isa("Catalyst::Plugin::Session")
 218         and $self->config->{'use_session'}
 219         and $user->supports("session")
 220     ) {
 221         $c->session->{__user_realm} = $self->name;
 222
 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);
 228         } else {
 229             $c->session->{__user} = $user->for_session;
 230         }
 231     }
 232     return $user;
 233 }
 234
 235 sub remove_persisted_user {
 236     my ($self, $c) = @_;
 237
 238     if (
 239         $c->isa("Catalyst::Plugin::Session")
 240         and $self->config->{'use_session'}
 241         and $c->session_is_valid
 242     ) {
 243         delete @{ $c->session }{qw/__user __user_realm/};
 244     }
 245 }
 246
 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 ) = @_;
 251
 252     return $self->persist_user($c, $user);
 253 }
 254
 255 sub from_session {
 256     my ($self, $c, $frozen_user) = @_;
 257
 258     return $self->store->from_session($c, $frozen_user);
 259 }
 260
 261
 262 __PACKAGE__;
 263
 264 __END__
 265
 266 =pod
 267
 268 =head1 NAME
 269
 270 Catalyst::Authentication::Realm - Base class for realm objects.
 271
 272 =head1 DESCRIPTION
 273
 274 =head1 CONFIGURATION
 275
 276 =over 4
 277
 278 =item class
 279
 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.
 285
 286 =item auto_create_user
 287
 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).
 290
 291 =item auto_update_user
 292
 293 Set this to true if you wish this realm to auto-update user accounts after
 294 authentication (most useful for remote authentication schemes).
 295
 296 =item use_session
 297
 298 Sets session usage for this particular realm - overriding the global use_sesion setting.
 299
 300
 301 =back
 302
 303 =head1 METHODS
 304
 305 =head2 new( $realmname, $config, $app )
 306
 307 Instantiantes this realm, plus the specified store and credential classes.
 308
 309 =head2 store( )
 310
 311 Returns an instance of the store object for this realm.
 312
 313 =head2 credential( )
 314
 315 Returns an instance of the credential object for this realm.
 316
 317 =head2 find_user( $authinfo, $c )
 318
 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.
 323
 324 =head2 authenticate( $c, $authinfo)
 325
 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;
 329
 330 =head1 USER PERSISTENCE
 331
 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
 336 any way you see fit.
 337
 338 =head2 persist_user($c, $user)
 339
 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
 346 your updates.
 347
 348 =head2 remove_persisted_user($c)
 349
 350 Removes any persisted user data.  By default, removes the user from the session.
 351
 352 =head2 user_is_restorable( $c )
 353
 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.
 357
 358 =head2 restore_user($c, [$frozen_user])
 359
 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.
 363
 364 =head2 failed_user_restore($c)
 365
 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).
 369
 370 =head2 from_session($c, $frozenuser )
 371
 372 Decodes the frozenuser information provided and returns an instantiated
 373 user object.  By default, this call is delegated to $store->from_session().
 374
 375 =head2 save_user_in_session($c, $user)
 376
 377 DEPRECATED.  Use persist_user instead.  (this simply calls persist_user)
 378
 379 =cut