lib/Catalyst/Plugin/Authentication.pm

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