Whitespace

[catagits/Catalyst-Plugin-Authentication.git] / lib / Catalyst / Authentication / Realm / Progressive.pm

diff --git a/lib/Catalyst/Authentication/Realm/Progressive.pm b/lib/Catalyst/Authentication/Realm/Progressive.pm
index 122dcbc..63d00a8 100644 (file)
--- a/lib/Catalyst/Authentication/Realm/Progressive.pm
+++ b/lib/Catalyst/Authentication/Realm/Progressive.pm
@@ -12,13 +12,18 @@ Catalyst::Authentication::Realm::Progressive - Authenticate against multiple rea
 
 =head1 SYNOPSIS
 
-This Realm allows an application to be built so that multiple realms are 
-supported and tried incrementally until a successful authentication.
+This Realm allows an application to use a single authenticate() call during
+which multiple realms are used and tried incrementally until one performs
+a successful authentication is accomplished.
 
-A simple use case is a Temporary Password that looks and acts exactly as a 
-regular password.  Without changing the authentication code, you can 
+A simple use case is a Temporary Password that looks and acts exactly as a
+regular password. Without changing the authentication code, you can
 authenticate against multiple realms.
 
+Another use might be to support a legacy website authentication system, trying
+the current auth system first, and upon failure, attempting authentication against
+the legacy system.
+
 =head2 EXAMPLE
 
 If your application has multiple realms to authenticate, such as a temporary
@@ -36,11 +41,11 @@ the normal realm.
                 # Modify the authinfo passed into authenticate by merging
                 # these hashes into the realm's authenticate call:
                 authinfo_munge => {
-                    'local'     => { 'realm' => 'normal' },
-                    'temp'      => { 'realm' => 'temp' },
+                    normal => { 'type' => 'normal' },
+                    temp   => { 'type' => 'temporary' },
                 }
             },
-            'normal' => {
+            normal => {
                 credential => {
                     class => 'Password',
                     password_field => 'secret',
@@ -49,7 +54,7 @@ the normal realm.
                 },
                 store => {
                     class      => 'DBIx::Class',
-                    user_class => 'Schema::Person::Identity',
+                    user_model => 'Schema::Person::Identity',
                     id_field   => 'id',
                 }
             },
@@ -62,19 +67,19 @@ the normal realm.
                 },
                 store => {
                     class    => 'DBIx::Class',
-                    user_class => 'Schema::Person::Identity',
+                    user_model => 'Schema::Person::Identity',
                     id_field   => 'id',
                 }
             },
         }
     }
- ); 
+ );
 
 Then, in your controller code, to attempt authentication against both realms
 you just have to do a simple authenticate call:
 
  if ( $c->authenticate({ id => $username, password => $password }) ) {
-     if ( $c->user->realm eq 'temp' ) {
+     if ( $c->user->type eq 'temporary' ) {
          # Force user to change password
      }
  }
@@ -85,7 +90,7 @@ you just have to do a simple authenticate call:
 
 =item realms
 
-An array reference consisting of each realm to attempt authentication against, 
+An array reference consisting of each realm to attempt authentication against,
 in the order listed.  If the realm does not exist, calling authenticate will
 die.
 
@@ -94,7 +99,7 @@ die.
 A hash reference keyed by realm names, with values being hash references to
 merge into the authinfo call that is subsequently passed into the realm's
 authenticate method.  This is useful if your store uses the same class for each
-realm, separated by some other token (in the L<EXAMPLE> authinfo_mungesection, 
+realm, separated by some other token (in the L<EXAMPLE> authinfo_mungesection,
 the 'realm' is a column on C<Schema::Person::Identity> that will be either
 'temp' or 'local', to ensure the query to fetch the user finds the right
 Identity record for that realm.
@@ -103,6 +108,10 @@ Identity record for that realm.
 
 =head1 METHODS
 
+=head2 new ($realmname, $config, $app)
+
+Constructs an instance of this realm.
+
 =head2 authenticate
 
 This method iteratively calls each realm listed in the C<realms> configuration
@@ -119,11 +128,11 @@ sub authenticate {
         unless ref $realms eq 'ARRAY';
     foreach my $realm_name ( @$realms ) {
         my $realm = $c->get_auth_realm( $realm_name );
-        carp "Unable to find realm: $realm_name, check configuration" 
+        carp "Unable to find realm: $realm_name, check configuration"
             unless $realm;
         my $auth = { %$authinfo };
         $auth->{realm} ||= $realm->name;
-        if ( my $info = $realm->config->{authinfo_munge}->{$realm->name} ) {
+        if ( my $info = $self->config->{authinfo_munge}->{$realm->name} ) {
             $auth = Catalyst::Utils::merge_hashes($auth, $info);
         }
         if ( my $obj = $realm->authenticate( $c, $auth ) ) {
@@ -134,6 +143,21 @@ sub authenticate {
     return;
 }
 
+## we can not rely on inheriting new() because in this case we do not
+## load a credential or store, which is what new() sets up in the
+## standard realm.  So we have to create our realm object, set our name
+## and return $self in order to avoid nasty warnings.
+
+sub new {
+    my ($class, $realmname, $config, $app) = @_;
+
+    my $self = { config => $config };
+    bless $self, $class;
+
+    $self->name($realmname);
+    return $self;
+}
+
 =head1 AUTHORS
 
 J. Shirley C<< <jshirley@cpan.org> >>