[Catalyst-commits] r7510 - in trunk/Catalyst-Plugin-Authentication:
. lib/Catalyst/Authentication
lib/Catalyst/Authentication/Credential lib/Catalyst/Plugin
lib/Catalyst/Plugin/Authentication
jayk at dev.catalyst.perl.org
jayk at dev.catalyst.perl.org
Mon Mar 17 16:21:52 GMT 2008
Author: jayk
Date: 2008-03-17 16:21:52 +0000 (Mon, 17 Mar 2008)
New Revision: 7510
Modified:
trunk/Catalyst-Plugin-Authentication/Changes
trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Authentication/Credential/Password.pm
trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Authentication/Realm.pm
trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication.pm
trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication/Internals.pod
Log:
Decoupling of Session and Auth-
all work related to persisting a user is now delegated to the realm object
Modified: trunk/Catalyst-Plugin-Authentication/Changes
===================================================================
--- trunk/Catalyst-Plugin-Authentication/Changes 2008-03-17 14:57:44 UTC (rev 7509)
+++ trunk/Catalyst-Plugin-Authentication/Changes 2008-03-17 16:21:52 UTC (rev 7510)
@@ -1,5 +1,20 @@
Revision history for Perl extension Catalyst::Plugin::Authentication
+0.11007 2008-03-17
+ - Documentation update on Password - to indicate proper field naming
+ - Decouple Authentication system from session. The realm class
+ now allows complete control over how a user is persisted across
+ requests.
+
+0.10006 2008-02-15
+ - Additional documentation for Realms
+ - Added update_user_in_session routine to allow re-saving of user data
+ into the session.
+
+0.10005 2008-01-24
+ - Bugfix release - correcting 'Plugin::Authentication' configuration
+ problem.
+
0.10004 2007-12-04
- Added some code for back-compatibility
Modified: trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Authentication/Credential/Password.pm
===================================================================
--- trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Authentication/Credential/Password.pm 2008-03-17 14:57:44 UTC (rev 7509)
+++ trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Authentication/Credential/Password.pm 2008-03-17 16:21:52 UTC (rev 7510)
@@ -275,7 +275,9 @@
depending on the storage class used, but is most likely something like
'password'. In fact, this is so common that if this is left out of the config,
it defaults to 'password'. This field is obtained from the user object using
-the get() method. Essentially: $user->get('passwordfieldname');
+the get() method. Essentially: $user->get('passwordfieldname');
+B<NOTE> If the password_field is something other than 'password', you must
+be sure to use that same field name when calling $c->authenticate().
=item password_type
@@ -359,7 +361,7 @@
most credential modules.) However, below is a description of the routines
required by L<Catalyst::Plugin::Authentication> for all credential modules.
-=head2 new( $config, $app )
+=head2 new( $config, $app, $realm )
Instantiate a new Password object using the configuration hash provided in
$config. A reference to the application is provided as the second argument.
Modified: trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Authentication/Realm.pm
===================================================================
--- trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Authentication/Realm.pm 2008-03-17 14:57:44 UTC (rev 7509)
+++ trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Authentication/Realm.pm 2008-03-17 16:21:52 UTC (rev 7510)
@@ -54,14 +54,22 @@
### we must eval the ensure_class_loaded - because we might need to try the old-style
### ::Plugin:: module naming if the standard method fails.
+ ## Note to self - catch second exception and bitch in detail?
+
eval {
Catalyst::Utils::ensure_class_loaded( $credentialclass );
};
if ($@) {
$app->log->warn( qq(Credential class "$credentialclass" not found, trying deprecated ::Plugin:: style naming. ) );
+ my $origcredentialclass = $credentialclass;
$credentialclass =~ s/Catalyst::Authentication/Catalyst::Plugin::Authentication/;
- Catalyst::Utils::ensure_class_loaded( $credentialclass );
+
+ eval { Catalyst::Utils::ensure_class_loaded( $credentialclass ); };
+ if ($@) {
+ Carp::croak "Unable to load credential class, " . $origcredentialclass . " OR " . $credentialclass .
+ " in realm " . $self->name;
+ }
}
eval {
@@ -70,8 +78,13 @@
if ($@) {
$app->log->warn( qq(Store class "$storeclass" not found, trying deprecated ::Plugin:: style naming. ) );
+ my $origstoreclass = $storeclass;
$storeclass =~ s/Catalyst::Authentication/Catalyst::Plugin::Authentication/;
- Catalyst::Utils::ensure_class_loaded( $storeclass );
+ eval { Catalyst::Utils::ensure_class_loaded( $storeclass ); };
+ if ($@) {
+ Carp::croak "Unable to load store class, " . $origstoreclass . " OR " . $storeclass .
+ " in realm " . $self->name;
+ }
}
# BACKWARDS COMPATIBILITY - if the store class does not define find_user, we define it in terms
@@ -132,21 +145,73 @@
}
}
-sub save_user_in_session {
- my ( $self, $c, $user ) = @_;
+sub user_is_restorable {
+ my ($self, $c) = @_;
+
+ return unless
+ $c->isa("Catalyst::Plugin::Session")
+ and $c->config->{'Plugin::Authentication'}{'use_session'}
+ and $c->session_is_valid;
- $c->session->{__user_realm} = $self->name;
+ return $c->session->{__user};
+}
+
+sub restore_user {
+ my ($self, $c, $frozen_user) = @_;
- # we want to ask the store for a user prepared for the session.
- # but older modules split this functionality between the user and the
- # store. We try the store first. If not, we use the old method.
- if ($self->store->can('for_session')) {
- $c->session->{__user} = $self->store->for_session($c, $user);
- } else {
- $c->session->{__user} = $user->for_session;
+ $frozen_user ||= $self->user_is_restorable($c);
+ return unless defined($frozen_user);
+
+ $c->_user( my $user = $self->from_session( $c, $frozen_user ) );
+
+ # this sets the realm the user originated in.
+ $user->auth_realm($self->name);
+
+ return $user;
+}
+
+sub persist_user {
+ my ($self, $c, $user) = @_;
+
+ if (
+ $c->isa("Catalyst::Plugin::Session")
+ and $c->config->{'Plugin::Authentication'}{'use_session'}
+ and $user->supports("session")
+ ) {
+ $c->session->{__user_realm} = $self->name;
+
+ # we want to ask the store for a user prepared for the session.
+ # but older modules split this functionality between the user and the
+ # store. We try the store first. If not, we use the old method.
+ if ($self->store->can('for_session')) {
+ $c->session->{__user} = $self->store->for_session($c, $user);
+ } else {
+ $c->session->{__user} = $user->for_session;
+ }
}
+ return $user;
}
+sub remove_persisted_user {
+ my ($self, $c) = @_;
+
+ if (
+ $c->isa("Catalyst::Plugin::Session")
+ and $c->config->{'Plugin::Authentication'}{'use_session'}
+ and $c->session_is_valid
+ ) {
+ delete @{ $c->session }{qw/__user __user_realm/};
+ }
+}
+
+## backwards compatibility - I don't think many people wrote realms since they
+## have only existed for a short time - but just in case.
+sub save_user_in_session {
+ my ( $self, $c, $user ) = @_;
+
+ return $self->persist_user($c, $user);
+}
+
sub from_session {
my ($self, $c, $frozen_user) = @_;
@@ -172,8 +237,11 @@
=item class
-By default this class is the default realm class. You can specify a custom
-realm class with this config parameter.
+By default this class is used by
+L<Catalyst::Plugin::Authentication|Catalyst::Plugin::Authentication> for all
+realms. The class parameter allows you to choose a different class to use for
+this realm. Creating a new Realm class can allow for authentication methods
+that fall outside the normal credential/store methodology.
=item auto_create_user
@@ -189,34 +257,42 @@
=head1 METHODS
-=head2 new( )
+=head2 new( $realmname, $config, $app )
Instantiantes this realm, plus the specified store and credential classes.
=head2 store( )
-Holds an instance of the store object for this realm.
+Returns an instance of the store object for this realm.
=head2 credential( )
-Holds an instance of the credential object for this realm.
+Returns an instance of the credential object for this realm.
-=head2 find_user( )
+=head2 find_user( $authinfo, $c )
-Delegates to the store object. Will also re-delegate auto_create_user and
-auto_update_user at this time, if necessary.
+Retrieves the user given the authentication information provided. This
+is most often called from the credential. The default realm class simply
+delegates this call the store object. If enabled, auto-creation and
+auto-updating of users is also handled here.
-=head2 authenticate( )
+=head2 authenticate( $c, $authinfo)
-Delegates to the credential objects and sets the authenticated user on success.
+Performs the authentication process for the current realm. The default
+realm class simply delegates this to the credential and sets
+the authenticated user on success. Returns the authenticated user object;
-=head2 save_user_in_session( )
+=head save_user_in_session($c, $user)
-Delegates to the store object.
+Used to save the user in a session. Saves $user in the current session,
+marked as originating in the current realm. Calls $store->for_session() by
+default. If for_session is not available in the store class, will attempt
+to call $user->for_session().
-=head2 from_session( )
+=head2 from_session($c, $frozenuser )
-Delegates to the store object.
+Triggers restoring of the user from data in the session. The default realm
+class simply delegates the call to $store->from_session($c, $frozenuser);
=cut
Modified: trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication/Internals.pod
===================================================================
--- trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication/Internals.pod 2008-03-17 14:57:44 UTC (rev 7509)
+++ trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication/Internals.pod 2008-03-17 16:21:52 UTC (rev 7510)
@@ -45,12 +45,13 @@
B<Realm Setup> - for each realm:
=over 4
+1) The Realm is instantiated using new() method
-1) The Store is instantiated using new() method
+2) The Store is instantiated using new() method
-2) The Credential Instantiated using new() method
+3) The Credential Instantiated using new() method
-3) Credential and Store objects tied to realm for use during requests
+4) Credential and Store objects tied to realm for use during requests
=back
@@ -64,20 +65,19 @@
=over 4
-1) Credential / Store objects retrieved for realm provided
+1) Credential object retrieved for realm provided
-2) Credential's authenticate() method called
+2) Credential's authenticate() method called with authinfo and realm object for current realm
=over 4
-The realm's store object and the authinfo hash provided to the
-credential object's authenticate call. In most cases the
-credential object will attempt to retrieve a user from the store
-provided by using the Store's find_user() method. It will then
-usually compare the retrieved user's information with the
-information provided in the $authinfo hash. This is how the
-default 'Password' credential functions. If the credentials match,
-the authenticate() method should return a user object.
+The realm object and the authinfo hash are provided to the credential object's
+authenticate call. In most cases the credential object will attempt to
+retrieve a user using the realm's find_user() method, which by default relays
+the call directly to the Store's find_user() method. It will then usually
+compare the retrieved user's information with the information provided in the
+$authinfo hash. This is how the default 'Password' credential functions. If
+the credentials match, the authenticate() method should return a user object.
=back
@@ -85,13 +85,13 @@
=over 4
-If the user object supports session storage, the successfully
-authenticated user will be placed in session storage. This is done
-by calling the store object's for_session() method, which should
-return serialized data (IE a scalar). This serialized data is
-passed back to the store via the from_session() method, so the
-data should contain enough information for the store to recreate /
-reload the user.
+If the user object supports session storage, the successfully authenticated
+user will be placed in session storage. This is done by calling the realm
+object's save_user_in_session() method. The save_user_in_session() routine by
+default calls the Store's for_session() method, which should return serialized
+data (IE a scalar). This serialized data is passed back to the store via the
+from_session() method, so the data should contain enough information for the
+store to recreate / reload the user.
=back
@@ -192,7 +192,7 @@
=over 4
-=item new( $config, $app )
+=item new( $config, $app, $realm )
The C<new()> method is called only once, during the setup process of
L<Catalyst::Plugin::Authentication|Catalyst::Plugin::Authentication>. The
@@ -359,14 +359,15 @@
=over 4
-=item new( $config, $app )
+=item new( $config, $app, $realm )
Like the Store method of the same name, the C<new()> method is called only
once, during the setup process of
L<Catalyst::Plugin::Authentication|Catalyst::Plugin::Authentication>. The
first argument, C<$config>, is a hash reference containing the configuration
information for the credential module. The second argument is a reference
-to the Catalyst application.
+to the Catalyst application. $realm is the instantiated Realm object, which
+you may use to access realm routines - such as find_user.
Again, when the credential's new() method is called, Catalyst
has not yet loaded the various controller and model classes.
@@ -374,13 +375,13 @@
The new method should perform any necessary setup required and instantiate
your credential object. It should return your instantiated credential.
-=item authenticate( $c, $authstore, $authinfo )
+=item authenticate( $c, $realm, $authinfo )
This is the workhorse of your credential. When $c->authenticate() is called
the L<Catalyst::Plugin::Authentication|Catalyst::Plugin::Authentication> module retrieves the
-store object from the realm and passes it, along with the $authinfo hash
+realm object and passes it, along with the $authinfo hash
to your credential's authenticate method. Your module should use the
-$authinfo hash to obtain the user from the store passed, and then perform
+$authinfo hash to obtain the user from the realm passed, and then perform
any credential verification steps necessary to authenticate the user. This
method should return the user object returned by the authentication store if
credential verification succeeded. It should return undef on failure.
@@ -394,7 +395,7 @@
attempting to retrieve the user from the store. It may also make sense for
your credential to perform activities which help to locate the user in
question, for example, finding a user id based on an encrypted token.
-In these scenarios, the $authinfo hash passed to the store's find_user()
+In these scenarios, the $authinfo hash passed to find_user()
can be different than that which is passed in to $c->authenticate(). Once
again this is perfectly acceptable if it makes sense for your credential,
though you are strongly advised to note this behavior clearly in your
Modified: trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication.pm
===================================================================
--- trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication.pm 2008-03-17 14:57:44 UTC (rev 7509)
+++ trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication.pm 2008-03-17 16:21:52 UTC (rev 7510)
@@ -20,8 +20,14 @@
# constant->import(have_want => eval { require Want });
#}
-our $VERSION = "0.10005";
+## NOTE TO SELF:
+## move user persistence into realm.
+## basically I'll provide 'persist_user' which will save the currently auth'd user.
+## 'restore_user' which will restore the user, and 'user_is_restorable' which is a
+## true/false on whether there is a user to restore.
+our $VERSION = "0.11000";
+
sub set_authenticated {
my ( $c, $user, $realmname ) = @_;
@@ -37,14 +43,9 @@
Catalyst::Exception->throw(
"set_authenticated called with nonexistant realm: '$realmname'.");
}
-
- if ( $c->isa("Catalyst::Plugin::Session")
- and $c->config->{'Plugin::Authentication'}{'use_session'}
- and $user->supports("session") )
- {
- $realm->save_user_in_session($c, $user);
- }
$user->auth_realm($realm->name);
+
+ $c->persist_user();
$c->NEXT::set_authenticated($user, $realmname);
}
@@ -64,10 +65,10 @@
}
# change this to allow specification of a realm - to verify the user is part of that realm
-# in addition to verifying that they exist.
+# in addition to verifying that they exist.
sub user_exists {
my $c = shift;
- return defined($c->_user) || defined($c->_user_in_session);
+ return defined($c->_user) || defined($c->_find_realm_for_persisted_user);
}
# works like user_exists - except only returns true if user
@@ -77,10 +78,13 @@
if (defined($c->_user)) {
return ($c->_user->auth_realm eq $realmname);
- } elsif (defined($c->_user_in_session)) {
- return ($c->session->{__user_realm} eq $realmname);
} else {
- return undef;
+ my $realm = $c->_find_realm_for_persisted_user;
+ if ($realm) {
+ return ($realm->name eq $realmname);
+ } else {
+ return undef;
+ }
}
}
@@ -100,17 +104,45 @@
}
}
+sub persist_user {
+ my $c = shift;
+
+ if ($c->user_exists) {
+
+ ## if we have a valid session handler - we store the
+ ## realm in the session. If not - we have to hope that
+ ## the realm can recognize it's frozen user somehow.
+ if ($c->isa("Catalyst::Plugin::Session") &&
+ $c->config->{'Plugin::Authentication'}{'use_session'} &&
+ $c->session_is_valid) {
+
+ $c->session->{'__user_realm'} = $c->_user->auth_realm;
+ }
+
+ my $realm = $c->get_auth_realm($c->_user->auth_realm);
+
+ # used to call $realm->save_user_in_session
+ $realm->persist_user($c, $c->user);
+ }
+}
+
+
+## this was a short lived method to update user information -
+## you should use persist_user instead.
+sub update_user_in_session {
+ my $c = shift;
+
+ return $c->persist_user;
+}
+
sub logout {
my $c = shift;
$c->user(undef);
- if (
- $c->isa("Catalyst::Plugin::Session")
- and $c->config->{'Plugin::Authentication'}{'use_session'}
- and $c->session_is_valid
- ) {
- delete @{ $c->session }{qw/__user __user_realm/};
+ my $realm = $c->_find_realm_for_persisted_user;
+ if ($realm) {
+ $realm->remove_persisted_user($c);
}
$c->NEXT::logout(@_);
@@ -130,31 +162,46 @@
}
-sub _user_in_session {
+sub _find_realm_for_persisted_user {
my $c = shift;
-
- return unless
- $c->isa("Catalyst::Plugin::Session")
+
+ my $realm;
+ if ($c->isa("Catalyst::Plugin::Session")
and $c->config->{'Plugin::Authentication'}{'use_session'}
- and $c->session_is_valid;
-
- return $c->session->{__user};
+ and $c->session_is_valid
+ and exists($c->session->{'__user_realm'})) {
+
+ $realm = $c->auth_realms->{$c->session->{'__user_realm'}};
+ if ($realm->user_is_restorable($c)) {
+ return $realm;
+ }
+ } else {
+ ## we have no choice but to ask each realm whether it has a persisted user.
+ foreach my $realmname (@{$c->_auth_realm_restore_order}) {
+ my $ret = $c->auth_realms->{$realmname}->user_is_restorable($c);
+ if ($ret) {
+ return $c->auth_realms->{$realmname};
+ }
+ }
+ }
+ return undef;
}
sub auth_restore_user {
my ( $c, $frozen_user, $realmname ) = @_;
- $frozen_user ||= $c->_user_in_session;
- return unless defined($frozen_user);
+ my $realm;
+ if (defined($realmname)) {
+ $realm = $c->get_auth_realm($realmname);
+ } else {
+ $realm = $c->_find_realm_for_persisted_user;
+ }
+ return unless $realm; # FIXME die unless? This is an internal inconsistency
- $realmname ||= $c->session->{__user_realm};
- return unless $realmname; # FIXME die unless? This is an internal inconsistency
-
- my $realm = $c->get_auth_realm($realmname);
- $c->_user( my $user = $realm->from_session( $c, $frozen_user ) );
+ $c->_user( my $user = $realm->restore_user( $c, $frozen_user ) );
# this sets the realm the user originated in.
- $user->auth_realm($realmname);
+ $user->auth_realm($realm->name);
return $user;
@@ -179,6 +226,19 @@
## make classdata where it is used.
$app->mk_classdata( '_auth_realms' => {});
+ ## the order to attempt restore in - If we don't have session - we have
+ ## no way to be sure where a frozen user came from - so we have to
+ ## ask each realm if it can restore the user. Unfortunately it is possible
+ ## that multiple realms could restore the user from the data we have -
+ ## So we have to determine at setup time what order to ask the realms in.
+ ## The default is to use the user_restore_priority values defined in the realm
+ ## config. if they are not defined - we go by alphabetical order. Note that
+ ## the 'default' realm always gets first chance at it unless it is explicitly
+ ## placed elsewhere by user_restore_priority. Remember this only comes
+ ## into play if session is disabled.
+
+ $app->mk_classdata( '_auth_realm_restore_order' => []);
+
my $cfg = $app->config->{'Plugin::Authentication'};
if (!defined($cfg)) {
if (exists($app->config->{'authentication'})) {
@@ -196,14 +256,39 @@
}
if (exists($cfg->{'realms'})) {
- foreach my $realm (keys %{$cfg->{'realms'}}) {
+
+ my %auth_restore_order;
+ my $authcount = 2;
+ my $defaultrealm = 'default';
+
+ foreach my $realm (sort keys %{$cfg->{'realms'}}) {
+
$app->setup_auth_realm($realm, $cfg->{'realms'}{$realm});
+
+ if (exists($cfg->{'realms'}{$realm}{'user_restore_priority'})) {
+ $auth_restore_order{$realm} = $cfg->{'realms'}{$realm}{'user_restore_priority'};
+ } else {
+ $auth_restore_order{$realm} = $authcount++;
+ }
}
- # if we have a 'default_realm' in the config hash and we don't already
+
+ # if we have a 'default_realm' in the config hash and we don't already
# have a realm called 'default', we point default at the realm specified
if (exists($cfg->{'default_realm'}) && !$app->get_auth_realm('default')) {
- $app->_set_default_auth_realm($cfg->{'default_realm'});
+ if ($app->_set_default_auth_realm($cfg->{'default_realm'})) {
+ $defaultrealm = $cfg->{'default_realm'};
+ $auth_restore_order{'default'} = $auth_restore_order{$cfg->{'default_realm'}};
+ delete($auth_restore_order{$cfg->{'default_realm'}});
+ }
}
+
+ ## if the default realm did not have a defined priority in it's config - we put it at the front.
+ if (!exists($cfg->{'realms'}{$defaultrealm}{'user_restore_priority'})) {
+ $auth_restore_order{'default'} = 1;
+ }
+
+ @{$app->_auth_realm_restore_order} = sort { $auth_restore_order{$a} <=> $auth_restore_order{$b} } keys %auth_restore_order;
+
} else {
## BACKWARDS COMPATIBILITY - if realms is not defined - then we are probably dealing
@@ -216,13 +301,14 @@
$cfg->{'stores'}{'default'} = $cfg->{'store'};
}
+ push @{$app->_auth_realm_restore_order}, 'default';
foreach my $storename (keys %{$cfg->{'stores'}}) {
my $realmcfg = {
store => { class => $cfg->{'stores'}{$storename} },
};
$app->setup_auth_realm($storename, $realmcfg);
}
- }
+ }
}
@@ -258,7 +344,9 @@
sub get_auth_realm {
my ($app, $realmname) = @_;
+
return $app->auth_realms->{$realmname};
+
}
@@ -788,6 +876,15 @@
Fetch a particular users details, matching the provided user info, from the realm
specified in $realm.
+=head2 persist_user()
+
+Under normal circumstances the user data is only saved to the session during
+initial authentication. This call causes the auth system to save the
+currently authenticated users data across requests. Useful if you have
+changed the user data and want to ensure that future requests reflect the
+most current data. Assumes that at the time of this call, $c->user
+contains the most current data.
+
=head1 INTERNAL METHODS
These methods are for Catalyst::Plugin::Authentication B<INTERNAL USE> only.
@@ -807,11 +904,6 @@
arguments to restore the user via the session. Can be called with arguments
when restoring a user from some other method. Currently not used in this way.
-=head2 $c->save_user_in_session( $user, $realmname )
-
-Used to save the user in a session. Saves $user in session, marked as
-originating in $realmname. Both arguments are required.
-
=head2 $c->auth_realms( )
Returns a hashref containing realmname -> realm instance pairs. Realm
More information about the Catalyst-commits
mailing list