lib/Catalyst/Plugin/Authentication.pm

   1 package Catalyst::Plugin::Authentication;
   2
   3 use base qw/Class::Accessor::Fast Class::Data::Inheritable/;
   4
   5 __PACKAGE__->mk_accessors(qw/_user/);
   6
   7 use strict;
   8 use warnings;
   9
  10 use Tie::RefHash;
  11 use Class::Inspector;
  12 use Catalyst::Authentication::Realm;
  13
  14 our $VERSION = "0.100092_01";
  15
  16 sub set_authenticated {
  17     my ( $c, $user, $realmname ) = @_;
  18
  19     $c->user($user);
  20     $c->request->{user} = $user;    # compatibility kludge
  21
  22     if (!$realmname) {
  23         $realmname = 'default';
  24     }
  25     my $realm = $c->get_auth_realm($realmname);
  26
  27     if (!$realm) {
  28         Catalyst::Exception->throw(
  29                 "set_authenticated called with nonexistant realm: '$realmname'.");
  30     }
  31     $user->auth_realm($realm->name);
  32
  33     $c->persist_user();
  34
  35     $c->NEXT::set_authenticated($user, $realmname);
  36 }
  37
  38 sub user {
  39     my $c = shift;
  40
  41     if (@_) {
  42         return $c->_user(@_);
  43     }
  44
  45     if ( defined($c->_user) ) {
  46         return $c->_user;
  47     } else {
  48         return $c->auth_restore_user;
  49     }
  50 }
  51
  52 # change this to allow specification of a realm - to verify the user is part of that realm
  53 # in addition to verifying that they exist.
  54 sub user_exists {
  55         my $c = shift;
  56         return defined($c->_user) || defined($c->find_realm_for_persisted_user);
  57 }
  58
  59 # works like user_exists - except only returns true if user
  60 # exists AND is in the realm requested.
  61 sub user_in_realm {
  62     my ($c, $realmname) = @_;
  63
  64     if (defined($c->_user)) {
  65         return ($c->_user->auth_realm eq $realmname);
  66     } else {
  67         my $realm = $c->find_realm_for_persisted_user;
  68         if ($realm) {
  69             return ($realm->name eq $realmname);
  70         } else {
  71             return undef;
  72         }
  73     }
  74 }
  75
  76 sub __old_save_user_in_session {
  77     my ( $c, $user, $realmname ) = @_;
  78
  79     $c->session->{__user_realm} = $realmname;
  80
  81     # we want to ask the store for a user prepared for the session.
  82     # but older modules split this functionality between the user and the
  83     # store.  We try the store first.  If not, we use the old method.
  84     my $realm = $c->get_auth_realm($realmname);
  85     if ($realm->{'store'}->can('for_session')) {
  86         $c->session->{__user} = $realm->{'store'}->for_session($c, $user);
  87     } else {
  88         $c->session->{__user} = $user->for_session;
  89     }
  90 }
  91
  92 sub persist_user {
  93     my $c = shift;
  94
  95     if ($c->user_exists) {
  96
  97         ## if we have a valid session handler - we store the
  98         ## realm in the session.  If not - we have to hope that
  99         ## the realm can recognize its frozen user somehow.
 100         if ($c->isa("Catalyst::Plugin::Session") &&
 101             $c->config->{'Plugin::Authentication'}{'use_session'} &&
 102             $c->session_is_valid) {
 103
 104             $c->session->{'__user_realm'} = $c->_user->auth_realm;
 105         }
 106
 107         my $realm = $c->get_auth_realm($c->_user->auth_realm);
 108
 109         # used to call $realm->save_user_in_session
 110         $realm->persist_user($c, $c->user);
 111     }
 112 }
 113
 114
 115 ## this was a short lived method to update user information -
 116 ## you should use persist_user instead.
 117 sub update_user_in_session {
 118     my $c = shift;
 119
 120     return $c->persist_user;
 121 }
 122
 123 sub logout {
 124     my $c = shift;
 125
 126     $c->user(undef);
 127
 128     my $realm = $c->find_realm_for_persisted_user;
 129     if ($realm) {
 130         $realm->remove_persisted_user($c);
 131     }
 132
 133     $c->NEXT::logout(@_);
 134 }
 135
 136 sub find_user {
 137     my ( $c, $userinfo, $realmname ) = @_;
 138
 139     $realmname ||= 'default';
 140     my $realm = $c->get_auth_realm($realmname);
 141
 142     if (!$realm) {
 143         Catalyst::Exception->throw(
 144                 "find_user called with nonexistant realm: '$realmname'.");
 145     }
 146     return $realm->find_user($userinfo, $c);
 147 }
 148
 149 ## Consider making this a public method. - would make certain things easier when
 150 ## dealing with things pre-auth restore.
 151 sub find_realm_for_persisted_user {
 152     my $c = shift;
 153
 154     my $realm;
 155     if ($c->isa("Catalyst::Plugin::Session")
 156         and $c->config->{'Plugin::Authentication'}{'use_session'}
 157         and $c->session_is_valid
 158         and exists($c->session->{'__user_realm'})) {
 159
 160         $realm = $c->auth_realms->{$c->session->{'__user_realm'}};
 161         if ($realm->user_is_restorable($c)) {
 162             return $realm;
 163         }
 164     } else {
 165         ## we have no choice but to ask each realm whether it has a persisted user.
 166         foreach my $realmname (@{$c->_auth_realm_restore_order}) {
 167             my $ret = $c->auth_realms->{$realmname}->user_is_restorable($c);
 168             if ($ret) {
 169                 return $c->auth_realms->{$realmname};
 170             }
 171         }
 172     }
 173     return undef;
 174 }
 175
 176 sub auth_restore_user {
 177     my ( $c, $frozen_user, $realmname ) = @_;
 178
 179     my $realm;
 180     if (defined($realmname)) {
 181         $realm = $c->get_auth_realm($realmname);
 182     } else {
 183         $realm = $c->find_realm_for_persisted_user;
 184     }
 185     return undef unless $realm; # FIXME die unless? This is an internal inconsistency
 186
 187     $c->_user( my $user = $realm->restore_user( $c, $frozen_user ) );
 188
 189     # this sets the realm the user originated in.
 190     $user->auth_realm($realm->name) if $user;
 191
 192     return $user;
 193
 194 }
 195
 196 # we can't actually do our setup in setup because the model has not yet been loaded.
 197 # So we have to trigger off of setup_finished.  :-(
 198 sub setup {
 199     my $app = shift;
 200
 201     $app->_authentication_initialize();
 202     $app->NEXT::setup(@_);
 203 }
 204
 205 ## the actual initialization routine. whee.
 206 sub _authentication_initialize {
 207     my $app = shift;
 208
 209     ## let's avoid recreating / configuring everything if we have already done it, eh?
 210     if ($app->can('_auth_realms')) { return };
 211
 212     ## make classdata where it is used.
 213     $app->mk_classdata( '_auth_realms' => {});
 214
 215     ## the order to attempt restore in - If we don't have session - we have
 216     ## no way to be sure where a frozen user came from - so we have to
 217     ## ask each realm if it can restore the user.  Unfortunately it is possible
 218     ## that multiple realms could restore the user from the data we have -
 219     ## So we have to determine at setup time what order to ask the realms in.
 220     ## The default is to use the user_restore_priority values defined in the realm
 221     ## config. if they are not defined - we go by alphabetical order.   Note that
 222     ## the 'default' realm always gets first chance at it unless it is explicitly
 223     ## placed elsewhere by user_restore_priority.  Remember this only comes
 224     ## into play if session is disabled.
 225
 226     $app->mk_classdata( '_auth_realm_restore_order' => []);
 227
 228     my $cfg = $app->config->{'Plugin::Authentication'};
 229         my $realmshash;
 230     if (!defined($cfg)) {
 231         if (exists($app->config->{'authentication'})) {
 232             $cfg = $app->config->{'authentication'};
 233             $app->config->{'Plugin::Authentication'} = $app->config->{'authentication'};
 234         } else {
 235             $cfg = {};
 236         }
 237     } else {
 238                 # the realmshash contains the various configured realms.  By default this is
 239                 # the main $app->config->{'Plugin::Authentication'} hash - but if that is
 240                 # not defined, or there is a subkey {'realms'} then we use that.
 241                 $realmshash = $cfg;
 242         }
 243
 244         ## If we have a sub-key of {'realms'} then we use that for realm configuration
 245         if (exists($cfg->{'realms'})) {
 246                 $realmshash = $cfg->{'realms'};
 247         }
 248
 249     # old default was to force use_session on.  This must remain for that
 250     # reason - but if use_session is already in the config, we respect its setting.
 251     if (!exists($cfg->{'use_session'})) {
 252         $cfg->{'use_session'} = 1;
 253     }
 254
 255     ## if we have a realms hash
 256     if (ref($realmshash) eq 'HASH') {
 257
 258         my %auth_restore_order;
 259         my $authcount = 2;
 260         my $defaultrealm = 'default';
 261
 262         foreach my $realm (sort keys %{$realmshash}) {
 263             if (ref($realmshash->{$realm}) eq 'HASH' &&
 264                                 (exists($realmshash->{$realm}{credential}) || exists($realmshash->{$realm}{class}))) {
 265
 266                     $app->setup_auth_realm($realm, $realmshash->{$realm});
 267
 268                     if (exists($realmshash->{$realm}{'user_restore_priority'})) {
 269                         $auth_restore_order{$realm} = $realmshash->{$realm}{'user_restore_priority'};
 270                     } else {
 271                         $auth_restore_order{$realm} = $authcount++;
 272                     }
 273                         }
 274         }
 275
 276         # if we have a 'default_realm' in the config hash and we don't already
 277         # have a realm called 'default', we point default at the realm specified
 278         if (exists($cfg->{'default_realm'}) && !$app->get_auth_realm('default')) {
 279             if ($app->_set_default_auth_realm($cfg->{'default_realm'})) {
 280                 $defaultrealm = $cfg->{'default_realm'};
 281                 $auth_restore_order{'default'} = $auth_restore_order{$cfg->{'default_realm'}};
 282                 delete($auth_restore_order{$cfg->{'default_realm'}});
 283             }
 284         }
 285
 286         ## if the default realm did not have a defined priority in its config - we put it at the front.
 287         if (!exists($realmshash->{$defaultrealm}{'user_restore_priority'})) {
 288             $auth_restore_order{'default'} = 1;
 289         }
 290
 291         @{$app->_auth_realm_restore_order} = sort { $auth_restore_order{$a} <=> $auth_restore_order{$b} } keys %auth_restore_order;
 292
 293     } else {
 294
 295         ## BACKWARDS COMPATIBILITY - if realms is not defined - then we are probably dealing
 296         ## with an old-school config.  The only caveat here is that we must add a classname
 297
 298         ## also - we have to treat {store} as {stores}{default} - because
 299         ## while it is not a clear as a valid config in the docs, it
 300         ## is functional with the old api. Whee!
 301         if (exists($cfg->{'store'}) && !exists($cfg->{'stores'}{'default'})) {
 302             $cfg->{'stores'}{'default'} = $cfg->{'store'};
 303         }
 304
 305         push @{$app->_auth_realm_restore_order}, 'default';
 306         foreach my $storename (keys %{$cfg->{'stores'}}) {
 307             my $realmcfg = {
 308                 store => { class => $cfg->{'stores'}{$storename} },
 309             };
 310             print STDERR "Foo, ok?\n";
 311             $app->setup_auth_realm($storename, $realmcfg);
 312         }
 313     }
 314
 315 }
 316
 317 # set up realmname.
 318 sub setup_auth_realm {
 319     my ($app, $realmname, $config) = @_;
 320
 321     my $realmclass = $config->{class};
 322
 323     if( !$realmclass ) {
 324         $realmclass = 'Catalyst::Authentication::Realm';
 325     } elsif ($realmclass !~ /^\+(.*)$/ ) {
 326         $realmclass = "Catalyst::Authentication::Realm::${realmclass}";
 327     } else {
 328         $realmclass = $1;
 329     }
 330
 331     Catalyst::Utils::ensure_class_loaded( $realmclass );
 332
 333     my $realm = $realmclass->new($realmname, $config, $app);
 334     if ($realm) {
 335         $app->auth_realms->{$realmname} = $realm;
 336     } else {
 337         $app->log->debug("realm initialization for '$realmname' failed.");
 338     }
 339     return $realm;
 340 }
 341
 342 sub auth_realms {
 343     my $self = shift;
 344     return($self->_auth_realms);
 345 }
 346
 347 sub get_auth_realm {
 348     my ($app, $realmname) = @_;
 349
 350     return $app->auth_realms->{$realmname};
 351
 352 }
 353
 354
 355 # Very internal method.  Vital Valuable Urgent, Do not touch on pain of death.
 356 # Using this method just assigns the default realm to be the value associated
 357 # with the realmname provided.  It WILL overwrite any real realm called 'default'
 358 # so can be very confusing if used improperly.  It's used properly already.
 359 # Translation: don't use it.
 360 sub _set_default_auth_realm {
 361     my ($app, $realmname) = @_;
 362
 363     if (exists($app->auth_realms->{$realmname})) {
 364         $app->auth_realms->{'default'} = $app->auth_realms->{$realmname};
 365     }
 366     return $app->get_auth_realm('default');
 367 }
 368
 369 sub authenticate {
 370     my ($app, $userinfo, $realmname) = @_;
 371
 372     if (!$realmname) {
 373         $realmname = 'default';
 374     }
 375
 376     my $realm = $app->get_auth_realm($realmname);
 377
 378     ## note to self - make authenticate throw an exception if realm is invalid.
 379
 380     if ($realm) {
 381         return $realm->authenticate($app, $userinfo);
 382     } else {
 383         Catalyst::Exception->throw(
 384                 "authenticate called with nonexistant realm: '$realmname'.");
 385
 386     }
 387     return undef;
 388 }
 389
 390 ## BACKWARDS COMPATIBILITY  -- Warning:  Here be monsters!
 391 #
 392 # What follows are backwards compatibility routines - for use with Stores and Credentials
 393 # that have not been updated to work with C::P::Authentication v0.10.
 394 # These are here so as to not break people's existing installations, but will go away
 395 # in a future version.
 396 #
 397 # The old style of configuration only supports a single store, as each store module
 398 # sets itself as the default store upon being loaded.  This is the only supported
 399 # 'compatibility' mode.
 400 #
 401
 402 sub get_user {
 403     my ( $c, $uid, @rest ) = @_;
 404
 405     return $c->find_user( {'id' => $uid, 'rest'=>\@rest }, 'default' );
 406 }
 407
 408
 409 ## this should only be called when using old-style authentication plugins.  IF this gets
 410 ## called in a new-style config - it will OVERWRITE the store of your default realm.  Don't do it.
 411 ## also - this is a partial setup - because no credential is instantiated... in other words it ONLY
 412 ## works with old-style auth plugins and C::P::Authentication in compatibility mode.  Trying to combine
 413 ## this with a realm-type config will probably crash your app.
 414 sub default_auth_store {
 415     my $self = shift;
 416
 417     my $realm = $self->get_auth_realm('default');
 418     if (!$realm) {
 419         $realm = $self->setup_auth_realm('default', { class => 'Compatibility' });
 420     }
 421     if ( my $new = shift ) {
 422         $realm->store($new);
 423
 424         my $storeclass;
 425         if (ref($new)) {
 426             $storeclass = ref($new);
 427         } else {
 428             $storeclass = $new;
 429         }
 430
 431         # BACKWARDS COMPATIBILITY - if the store class does not define find_user, we define it in terms
 432         # of get_user and add it to the class.  this is because the auth routines use find_user,
 433         # and rely on it being present. (this avoids per-call checks)
 434         if (!$storeclass->can('find_user')) {
 435             no strict 'refs';
 436             *{"${storeclass}::find_user"} = sub {
 437                                                     my ($self, $info) = @_;
 438                                                     my @rest = @{$info->{rest}} if exists($info->{rest});
 439                                                     $self->get_user($info->{id}, @rest);
 440                                                 };
 441         }
 442     }
 443
 444     return $self->get_auth_realm('default')->store;
 445 }
 446
 447 ## BACKWARDS COMPATIBILITY
 448 ## this only ever returns a hash containing 'default' - as that is the only
 449 ## supported mode of calling this.
 450 sub auth_store_names {
 451     my $self = shift;
 452
 453     my %hash = (  $self->get_auth_realm('default')->store => 'default' );
 454 }
 455
 456 sub get_auth_store {
 457     my ( $self, $name ) = @_;
 458
 459     if ($name ne 'default') {
 460         Carp::croak "get_auth_store called on non-default realm '$name'. Only default supported in compatibility mode";
 461     } else {
 462         $self->default_auth_store();
 463     }
 464 }
 465
 466 sub get_auth_store_name {
 467     my ( $self, $store ) = @_;
 468     return 'default';
 469 }
 470
 471 # sub auth_stores is only used internally - here for completeness
 472 sub auth_stores {
 473     my $self = shift;
 474
 475     my %hash = ( 'default' => $self->get_auth_realm('default')->store);
 476 }
 477
 478 __PACKAGE__;
 479
 480 __END__
 481
 482 =pod
 483
 484 =head1 NAME
 485
 486 Catalyst::Plugin::Authentication - Infrastructure plugin for the Catalyst
 487 authentication framework.
 488
 489 =head1 SYNOPSIS
 490
 491     use Catalyst qw/
 492         Authentication
 493     /;
 494
 495     # later on ...
 496     $c->authenticate({ username => 'myusername',
 497                        password => 'mypassword' });
 498     my $age = $c->user->get('age');
 499     $c->logout;
 500
 501 =head1 DESCRIPTION
 502
 503 The authentication plugin provides generic user support for Catalyst apps. It
 504 is the basis for both authentication (checking the user is who they claim to
 505 be), and authorization (allowing the user to do what the system authorises
 506 them to do).
 507
 508 Using authentication is split into two parts. A Store is used to actually
 509 store the user information, and can store any amount of data related to the
 510 user. Credentials are used to verify users, using information from the store,
 511 given data from the frontend. A Credential and a Store are paired to form a
 512 'Realm'. A Catalyst application using the authentication framework must have
 513 at least one realm, and may have several.
 514
 515 To implement authentication in a Catalyst application you need to add this
 516 module, and specify at least one realm in the configuration.
 517
 518 Authentication data can also be stored in a session, if the application
 519 is using the L<Catalyst::Plugin::Session> module.
 520
 521 B<NOTE> in version 0.10 of this module, the interface to this module changed.
 522 Please see L</COMPATIBILITY ROUTINES> for more information.
 523
 524 =head1 INTRODUCTION
 525
 526 =head2 The Authentication/Authorization Process
 527
 528 Web applications typically need to identify a user - to tell the user apart
 529 from other users. This is usually done in order to display private information
 530 that is only that user's business, or to limit access to the application so
 531 that only certain entities can access certain parts.
 532
 533 This process is split up into several steps. First you ask the user to identify
 534 themselves. At this point you can't be sure that the user is really who they
 535 claim to be.
 536
 537 Then the user tells you who they are, and backs this claim with some piece of
 538 information that only the real user could give you. For example, a password is
 539 a secret that is known to both the user and you. When the user tells you this
 540 password you can assume they're in on the secret and can be trusted (ignore
 541 identity theft for now). Checking the password, or any other proof is called
 542 B<credential verification>.
 543
 544 By this time you know exactly who the user is - the user's identity is
 545 B<authenticated>. This is where this module's job stops, and your application
 546 or other plugins step in.
 547
 548 The next logical step is B<authorization>, the process of deciding what a user
 549 is (or isn't) allowed to do. For example, say your users are split into two
 550 main groups - regular users and administrators. You want to verify that the
 551 currently logged in user is indeed an administrator before performing the
 552 actions in an administrative part of your application. These decisions may be
 553 made within your application code using just the information available after
 554 authentication, or it may be facilitated by a number of plugins.
 555
 556 =head2 The Components In This Framework
 557
 558 =head3 Realms
 559
 560 Configuration of the Catalyst::Plugin::Authentication framework is done in
 561 terms of realms. In simplest terms, a realm is a pairing of a Credential
 562 verifier and a User storage (Store) backend. As of version 0.10003, realms are
 563 now objects that you can create and customize.
 564
 565 An application can have any number of Realms, each of which operates
 566 independent of the others. Each realm has a name, which is used to identify it
 567 as the target of an authentication request. This name can be anything, such as
 568 'users' or 'members'. One realm must be defined as the default_realm, which is
 569 used when no realm name is specified. More information about configuring
 570 realms is available in the configuration section.
 571
 572 =head3 Credential Verifiers
 573
 574 When user input is transferred to the L<Catalyst> application
 575 (typically via form inputs) the application may pass this information
 576 into the authentication system through the C<< $c->authenticate() >>
 577 method.  From there, it is passed to the appropriate Credential
 578 verifier.
 579
 580 These plugins check the data, and ensure that it really proves the user is who
 581 they claim to be.
 582
 583 Credential verifiers compatible with versions of this module 0.10x and
 584 upwards should be in the namespace
 585 C<Catalyst::Authentication::Credential>.
 586
 587 =head3 Storage Backends
 588
 589 The authentication data also identifies a user, and the Storage backend modules
 590 use this data to locate and return a standardized object-oriented
 591 representation of a user.
 592
 593 When a user is retrieved from a store it is not necessarily authenticated.
 594 Credential verifiers accept a set of authentication data and use this
 595 information to retrieve the user from the store they are paired with.
 596
 597 Storage backends compatible with versions of this module 0.10x and
 598 upwards should be in the namespace
 599 C<Catalyst::Authentication::Store>.
 600
 601 =head3 The Core Plugin
 602
 603 This plugin on its own is the glue, providing realm configuration, session
 604 integration, and other goodness for the other plugins.
 605
 606 =head3 Other Plugins
 607
 608 More layers of plugins can be stacked on top of the authentication code. For
 609 example, L<Catalyst::Plugin::Session::PerUser> provides an abstraction of
 610 browser sessions that is more persistent per user.
 611 L<Catalyst::Plugin::Authorization::Roles> provides an accepted way to separate
 612 and group users into categories, and then check which categories the current
 613 user belongs to.
 614
 615 =head1 EXAMPLE
 616
 617 Let's say we were storing users in a simple Perl hash. Users are
 618 verified by supplying a password which is matched within the hash.
 619
 620 This means that our application will begin like this:
 621
 622     package MyApp;
 623
 624     use Catalyst qw/
 625         Authentication
 626     /;
 627
 628     __PACKAGE__->config->{'Plugin::Authentication'} =
 629                 {
 630                     default => {
 631                         credential => {
 632                             class => 'Password',
 633                             password_field => 'password',
 634                             password_type => 'clear'
 635                         },
 636                         store => {
 637                             class => 'Minimal',
 638                                 users => {
 639                                     bob => {
 640                                         password => "s00p3r",
 641                                         editor => 'yes',
 642                                         roles => [qw/edit delete/],
 643                                     },
 644                                     william => {
 645                                         password => "s3cr3t",
 646                                         roles => [qw/comment/],
 647                                     }
 648                                 }
 649                             }
 650                         }
 651                 };
 652
 653 This tells the authentication plugin what realms are available, which
 654 credential and store modules are used, and the configuration of each. With
 655 this code loaded, we can now attempt to authenticate users.
 656
 657 To show an example of this, let's create an authentication controller:
 658
 659     package MyApp::Controller::Auth;
 660
 661     sub login : Local {
 662         my ( $self, $c ) = @_;
 663
 664         if (    my $user     = $c->req->params->{user}
 665             and my $password = $c->req->params->{password} )
 666         {
 667             if ( $c->authenticate( { username => $user,
 668                                      password => $password } ) ) {
 669                 $c->res->body( "hello " . $c->user->get("name") );
 670             } else {
 671                 # login incorrect
 672             }
 673         }
 674         else {
 675             # invalid form input
 676         }
 677     }
 678
 679 This code should be self-explanatory. If all the necessary fields are supplied,
 680 call the C<authenticate> method on the context object. If it succeeds the
 681 user is logged in.
 682
 683 The credential verifier will attempt to retrieve the user whose
 684 details match the authentication information provided to
 685 C<< $c->authenticate() >>. Once it fetches the user the password is
 686 checked and if it matches the user will be B<authenticated> and
 687 C<< $c->user >> will contain the user object retrieved from the store.
 688
 689 In the above case, the default realm is checked, but we could just as easily
 690 check an alternate realm. If this were an admin login, for example, we could
 691 authenticate on the admin realm by simply changing the C<< $c->authenticate() >>
 692 call:
 693
 694     if ( $c->authenticate( { username => $user,
 695                              password => $password }, 'admin' ) ) {
 696         $c->res->body( "hello " . $c->user->get("name") );
 697     } ...
 698
 699
 700 Now suppose we want to restrict the ability to edit to a user with an
 701 'editor' value of yes.
 702
 703 The restricted action might look like this:
 704
 705     sub edit : Local {
 706         my ( $self, $c ) = @_;
 707
 708         $c->detach("unauthorized")
 709           unless $c->user_exists
 710           and $c->user->get('editor') eq 'yes';
 711
 712         # do something restricted here
 713     }
 714
 715 (Note that if you have multiple realms, you can use
 716 C<< $c->user_in_realm('realmname') >> in place of
 717 C<< $c->user_exists(); >> This will essentially perform the same
 718 verification as user_exists, with the added requirement that if there
 719 is a user, it must have come from the realm specified.)
 720
 721 The above example is somewhat similar to role based access control.
 722 L<Catalyst::Authentication::Store::Minimal> treats the roles field as
 723 an array of role names. Let's leverage this. Add the role authorization
 724 plugin:
 725
 726     use Catalyst qw/
 727         ...
 728         Authorization::Roles
 729     /;
 730
 731     sub edit : Local {
 732         my ( $self, $c ) = @_;
 733
 734         $c->detach("unauthorized") unless $c->check_user_roles("edit");
 735
 736         # do something restricted here
 737     }
 738
 739 This is somewhat simpler and will work if you change your store, too, since the
 740 role interface is consistent.
 741
 742 Let's say your app grows, and you now have 10,000 users. It's no longer
 743 efficient to maintain a hash of users, so you move this data to a database.
 744 You can accomplish this simply by installing the L<DBIx::Class|Catalyst::Authentication::Store::DBIx::Class> Store and
 745 changing your config:
 746
 747     __PACKAGE__->config->{'Plugin::Authentication'} =
 748                     {
 749                         default_realm => 'members',
 750                         members => {
 751                             credential => {
 752                                 class => 'Password',
 753                                 password_field => 'password',
 754                                 password_type => 'clear'
 755                             },
 756                             store => {
 757                                 class => 'DBIx::Class',
 758                                     user_class => 'MyApp::Users',
 759                                     role_column => 'roles'
 760                                 }
 761                         }
 762                     };
 763
 764 The authentication system works behind the scenes to load your data from the
 765 new source. The rest of your application is completely unchanged.
 766
 767
 768 =head1 CONFIGURATION
 769
 770     # example
 771     __PACKAGE__->config->{'Plugin::Authentication'} =
 772                 {
 773                     default_realm => 'members',
 774
 775                     members => {
 776                         credential => {
 777                             class => 'Password',
 778                             password_field => 'password',
 779                             password_type => 'clear'
 780                         },
 781                         store => {
 782                             class => 'DBIx::Class',
 783                             user_class => 'MyApp::Users',
 784                             role_column => 'roles'
 785                         }
 786                         },
 787                         admins => {
 788                             credential => {
 789                                 class => 'Password',
 790                                 password_field => 'password',
 791                             password_type => 'clear'
 792                             },
 793                             store => {
 794                                 class => '+MyApp::Authentication::Store::NetAuth',
 795                                 authserver => '192.168.10.17'
 796                             }
 797                         }
 798                 };
 799
 800 =over 4
 801
 802 =item use_session
 803
 804 Whether or not to store the user's logged in state in the session, if the
 805 application is also using L<Catalyst::Plugin::Session>. This
 806 value is set to true per default.
 807
 808 =item default_realm
 809
 810 This defines which realm should be used as when no realm is provided to methods
 811 that require a realm such as authenticate or find_user.
 812
 813 =item realm refs
 814
 815 The Plugin::Authentication config hash contains the series of realm
 816 configurations you want to use for your app. The only rule here is
 817 that there must be at least one. A realm consists of a name, which is used
 818 to reference the realm, a credential and a store.  You may also put your
 819 realm configurations within a subelement called 'realms' if you desire to
 820 separate them from the remainder of your configuration.  Note that if you use
 821 a 'realms' subelement, you must put ALL of your realms within it.
 822
 823 You can also specify a realm class to instantiate instead of the default
 824 L<Catalyst::Authentication::Realm> class using the 'class' element within the
 825 realm config.
 826
 827 Each realm config contains two hashes, one called 'credential' and one called
 828 'store', each of which provide configuration details to the respective modules.
 829 The contents of these hashes is specific to the module being used, with the
 830 exception of the 'class' element, which tells the core Authentication module the
 831 classname to instantiate.
 832
 833 The 'class' element follows the standard Catalyst mechanism of class
 834 specification. If a class is prefixed with a +, it is assumed to be a complete
 835 class name. Otherwise it is considered to be a portion of the class name. For
 836 credentials, the classname 'B<Password>', for example, is expanded to
 837 Catalyst::Authentication::Credential::B<Password>. For stores, the
 838 classname 'B<storename>' is expanded to:
 839 Catalyst::Authentication::Store::B<storename>.
 840
 841 =back
 842
 843 =head1 METHODS
 844
 845 =head2 $c->authenticate( $userinfo [, $realm ])
 846
 847 Attempts to authenticate the user using the information in the $userinfo hash
 848 reference using the realm $realm. $realm may be omitted, in which case the
 849 default realm is checked.
 850
 851 =head2 $c->user( )
 852
 853 Returns the currently logged in user, or undef if there is none.
 854
 855 =head2 $c->user_exists( )
 856
 857 Returns true if a user is logged in right now. The difference between
 858 user_exists and user is that user_exists will return true if a user is logged
 859 in, even if it has not been yet retrieved from the storage backend. If you only
 860 need to know if the user is logged in, depending on the storage mechanism this
 861 can be much more efficient.
 862
 863 =head2 $c->user_in_realm( $realm )
 864
 865 Works like user_exists, except that it only returns true if a user is both
 866 logged in right now and was retrieved from the realm provided.
 867
 868 =head2 $c->logout( )
 869
 870 Logs the user out. Deletes the currently logged in user from C<< $c->user >> and the session.
 871
 872 =head2 $c->find_user( $userinfo, $realm )
 873
 874 Fetch a particular users details, matching the provided user info, from the realm
 875 specified in $realm.
 876
 877 =head2 persist_user()
 878
 879 Under normal circumstances the user data is only saved to the session during
 880 initial authentication.  This call causes the auth system to save the
 881 currently authenticated user's data across requests.  Useful if you have
 882 changed the user data and want to ensure that future requests reflect the
 883 most current data.  Assumes that at the time of this call, $c->user
 884 contains the most current data.
 885
 886 =head2 find_realm_for_persisted_user()
 887
 888 Private method, do not call from user code!
 889
 890 =head1 INTERNAL METHODS
 891
 892 These methods are for Catalyst::Plugin::Authentication B<INTERNAL USE> only.
 893 Please do not use them in your own code, whether application or credential /
 894 store modules. If you do, you will very likely get the nasty shock of having
 895 to fix / rewrite your code when things change. They are documented here only
 896 for reference.
 897
 898 =head2 $c->set_authenticated( $user, $realmname )
 899
 900 Marks a user as authenticated. This is called from within the authenticate
 901 routine when a credential returns a user. $realmname defaults to 'default'
 902
 903 =head2 $c->auth_restore_user( $user, $realmname )
 904
 905 Used to restore a user from the session. In most cases this is called without
 906 arguments to restore the user via the session. Can be called with arguments
 907 when restoring a user from some other method.  Currently not used in this way.
 908
 909 =head2 $c->auth_realms( )
 910
 911 Returns a hashref containing realmname -> realm instance pairs. Realm
 912 instances contain an instantiated store and credential object as the 'store'
 913 and 'credential' elements, respectively
 914
 915 =head2 $c->get_auth_realm( $realmname )
 916
 917 Retrieves the realm instance for the realmname provided.
 918
 919 =head2 $c->update_user_in_session
 920
 921 This was a short-lived method to update user information - you should use persist_user instead.
 922
 923 =head1 SEE ALSO
 924
 925 This list might not be up to date.  Below are modules known to work with the updated
 926 API of 0.10 and are therefore compatible with realms.
 927
 928 =head2 Realms
 929
 930 L<Catalyst::Authentication::Realm>
 931
 932 =head2 User Storage Backends
 933
 934 L<Catalyst::Authentication::Store::Minimal>,
 935 L<Catalyst::Authentication::Store::DBIx::Class>,
 936
 937 =head2 Credential verification
 938
 939 L<Catalyst::Authentication::Credential::Password>,
 940
 941 =head2 Authorization
 942
 943 L<Catalyst::Plugin::Authorization::ACL>,
 944 L<Catalyst::Plugin::Authorization::Roles>
 945
 946 =head2 Internals Documentation
 947
 948 L<Catalyst::Plugin::Authentication::Internals>
 949
 950 =head2 Misc
 951
 952 L<Catalyst::Plugin::Session>,
 953 L<Catalyst::Plugin::Session::PerUser>
 954
 955 =head1 DON'T SEE ALSO
 956
 957 This module along with its sub plugins deprecate a great number of other
 958 modules. These include L<Catalyst::Plugin::Authentication::Simple>,
 959 L<Catalyst::Plugin::Authentication::CDBI>.
 960
 961 At the time of writing these plugins have not yet been replaced or updated, but
 962 should be eventually: L<Catalyst::Plugin::Authentication::OpenID>,
 963 L<Catalyst::Plugin::Authentication::CDBI::Basic>,
 964 L<Catalyst::Plugin::Authentication::Basic::Remote>.
 965
 966 =head1 INCOMPATABILITIES
 967
 968 The realms-based configuration and functionality of the 0.10 update
 969 of L<Catalyst::Plugin::Authentication> required a change in the API used by
 970 credentials and stores.  It has a compatibility mode which allows use of
 971 modules that have not yet been updated. This, however, completely mimics the
 972 older api and disables the new realm-based features. In other words you cannot
 973 mix the older credential and store modules with realms, or realm-based
 974 configs. The changes required to update modules are relatively minor and are
 975 covered in L<Catalyst::Plugin::Authentication::Internals>.  We hope that most
 976 modules will move to the compatible list above very quickly.
 977
 978 =head1 COMPATIBILITY ROUTINES
 979
 980 In version 0.10 of L<Catalyst::Plugin::Authentication>, the API
 981 changed. For app developers, this change is fairly minor, but for
 982 Credential and Store authors, the changes are significant.
 983
 984 Please see the documentation in version 0.09 of
 985 Catalyst::Plugin::Authentication for a better understanding of how the old API
 986 functioned.
 987
 988 The items below are still present in the plugin, though using them is
 989 deprecated. They remain only as a transition tool, for those sites which can
 990 not yet be upgraded to use the new system due to local customizations or use
 991 of Credential / Store modules that have not yet been updated to work with the
 992 new API.
 993
 994 These routines should not be used in any application using realms
 995 functionality or any of the methods described above. These are for reference
 996 purposes only.
 997
 998 =head2 $c->login( )
 999
1000 This method is used to initiate authentication and user retrieval. Technically
1001 this is part of the old Password credential module and it still resides in the
1002 L<Password|Catalyst::Plugin::Authentication::Credential::Password> class. It is
1003 included here for reference only.
1004
1005 =head2 $c->default_auth_store( )
1006
1007 Return the store whose name is 'default'.
1008
1009 This is set to C<< $c->config->{'Plugin::Authentication'}{store} >> if that value exists,
1010 or by using a Store plugin:
1011
1012     # load the Minimal authentication store.
1013         use Catalyst qw/Authentication Authentication::Store::Minimal/;
1014
1015 Sets the default store to
1016 L<Catalyst::Plugin::Authentication::Store::Minimal>.
1017
1018 =head2 $c->get_auth_store( $name )
1019
1020 Return the store whose name is $name.
1021
1022 =head2 $c->get_auth_store_name( $store )
1023
1024 Return the name of the store $store.
1025
1026 =head2 $c->auth_stores( )
1027
1028 A hash keyed by name, with the stores registered in the app.
1029
1030 =head2 $c->register_auth_stores( %stores_by_name )
1031
1032 Register stores into the application.
1033
1034 =head2 $c->auth_store_names( )
1035
1036 =head2 $c->get_user( )
1037
1038 =head2 $c->setup( )
1039
1040 =head2 $c->setup_auth_realm( )
1041
1042 =head1 AUTHORS
1043
1044 Yuval Kogman, C<nothingmuch@woobling.org>
1045
1046 Jay Kuri, C<jayk@cpan.org>
1047
1048 Jess Robinson
1049
1050 David Kamholz
1051
1052 Tomas Doran (t0m), C<bobtfish@bobtfish.net>
1053
1054 =head1 COPYRIGHT & LICENSE
1055
1056         Copyright (c) 2005 the aforementioned authors. All rights
1057         reserved. This program is free software; you can redistribute
1058         it and/or modify it under the same terms as Perl itself.
1059
1060 =cut
1061