[Catalyst-commits] r7058 - in trunk/Catalyst-Plugin-Authentication:
. lib/Catalyst/Plugin lib/Catalyst/Plugin/Authentication
lib/Catalyst/Plugin/Authentication/Credential
lib/Catalyst/Plugin/Authentication/Realm
lib/Catalyst/Plugin/Authentication/Store
lib/Catalyst/Plugin/Authentication/User
bricas at dev.catalyst.perl.org
bricas at dev.catalyst.perl.org
Thu Oct 25 17:14:44 GMT 2007
Author: bricas
Date: 2007-10-25 17:14:43 +0100 (Thu, 25 Oct 2007)
New Revision: 7058
Modified:
trunk/Catalyst-Plugin-Authentication/Changes
trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication.pm
trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication/Credential/Password.pm
trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication/Realm.pm
trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication/Realm/Compatibility.pm
trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication/Store/Minimal.pm
trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication/Store/Null.pm
trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication/User.pm
trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication/User/Hash.pm
Log:
doc updates
Modified: trunk/Catalyst-Plugin-Authentication/Changes
===================================================================
--- trunk/Catalyst-Plugin-Authentication/Changes 2007-10-25 00:11:07 UTC (rev 7057)
+++ trunk/Catalyst-Plugin-Authentication/Changes 2007-10-25 16:14:43 UTC (rev 7058)
@@ -4,7 +4,13 @@
- Added a "Null" store for credentials that don't require real stores.
- Make realms bonafide objects
- Added auto_update_user and auto_create_user options to the Realm object
+ - Doc updates
+ [POSSIBLE INCOMPATIBILITIES]
+ - authenticate() in credentials are now passed a realm object instead of
+ a store object. A realm object still implements find_user() so unless
+ you're doing something special you won't notice the difference.
+
0.10002 2007-07-22
- $user->store() should NOT be set by C::P::Auth - if it's needed - it
should be set by whatever module creates the user. We use realm for
Modified: trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication/Credential/Password.pm
===================================================================
--- trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication/Credential/Password.pm 2007-10-25 00:11:07 UTC (rev 7057)
+++ trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication/Credential/Password.pm 2007-10-25 16:14:43 UTC (rev 7058)
@@ -1,9 +1,10 @@
package Catalyst::Plugin::Authentication::Credential::Password;
-use base qw/Class::Accessor::Fast/;
use strict;
use warnings;
+use base qw/Class::Accessor::Fast/;
+
use Scalar::Util ();
use Catalyst::Exception ();
use Digest ();
@@ -358,10 +359,8 @@
most credential modules.) However, below is a description of the routines
required by L<Catalyst::Plugin::Authentication> for all credential modules.
-=over 4
+=head2 new( $config, $app )
-=item new ( $config, $app )
-
Instantiate a new Password object using the configuration hash provided in
$config. A reference to the application is provided as the second argument.
Note to credential module authors: new() is called during the application's
@@ -369,9 +368,9 @@
loaded. The practical upshot of this is that things like $c->model(...) will
not function as expected.
-=item authenticate ( $authinfo, $c )
+=head2 authenticate( $authinfo, $c )
Try to log a user in, receives a hashref containing authentication information
as the first argument, and the current context as the second.
-=back
+=cut
Modified: trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication/Realm/Compatibility.pm
===================================================================
--- trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication/Realm/Compatibility.pm 2007-10-25 00:11:07 UTC (rev 7057)
+++ trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication/Realm/Compatibility.pm 2007-10-25 16:14:43 UTC (rev 7058)
@@ -35,12 +35,8 @@
=head1 METHODS
-=over 4
+=head2 new( )
-=item new
-
Returns a, basically empty, realm object.
-=back
-
=cut
Modified: trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication/Realm.pm
===================================================================
--- trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication/Realm.pm 2007-10-25 00:11:07 UTC (rev 7057)
+++ trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication/Realm.pm 2007-10-25 16:14:43 UTC (rev 7058)
@@ -144,22 +144,31 @@
=head1 DESCRIPTION
-=head1 METHODS
+=head1 CONFIGURATION
=over 4
-=item new
+=item class
-=item find_user
+=item auto_create_user
-=item authenticate
+=item auto_update_user
-=item save_user_in_session
+=back
-=item from_session
+=head1 METHODS
+=head2 new( )
+
+=head2 find_user( )
+
+=head2 authenticate( )
+
+=head2 save_user_in_session( )
+
+=head2 from_session( )
+
=back
=cut
-
Modified: trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication/Store/Minimal.pm
===================================================================
--- trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication/Store/Minimal.pm 2007-10-25 00:11:07 UTC (rev 7057)
+++ trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication/Store/Minimal.pm 2007-10-25 16:14:43 UTC (rev 7058)
@@ -12,7 +12,7 @@
}
sub new {
- my ( $class, $config, $app) = @_;
+ my ( $class, $config, $app, $realm) = @_;
bless { userhash => $config->{'users'} }, $class;
}
@@ -189,14 +189,12 @@
most authentication stores) However, below is a description of the routines
required by L<Catalyst::Plugin::Authentication> for all authentication stores.
-=over 4
+=head2 new( $config, $app, $realm )
-=item new ( $config, $app )
-
Constructs a new store object, which uses the user element of the supplied config
hash ref as it's backing structure.
-=item find_user ( $authinfo, $c )
+=head2 find_user( $authinfo, $c )
Keys the hash by the 'id' or 'username' element in the authinfo hash and returns the user.
@@ -205,16 +203,14 @@
If the return value is unblessed it will be blessed as
L<Catalyst::Plugin::Authentication::User::Hash>.
-=item from_session $id
+=head2 from_session( $id )
Delegates to C<get_user>.
-=item user_supports
+=head2 user_supports( )
Chooses a random user from the hash and delegates to it.
-=back
-
=cut
Modified: trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication/Store/Null.pm
===================================================================
--- trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication/Store/Null.pm 2007-10-25 00:11:07 UTC (rev 7057)
+++ trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication/Store/Null.pm 2007-10-25 16:14:43 UTC (rev 7058)
@@ -12,7 +12,7 @@
}
sub new {
- my ( $class, $config, $app) = @_;
+ my ( $class, $config, $app, $realm ) = @_;
bless { _config => $config }, $class;
}
Modified: trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication/User/Hash.pm
===================================================================
--- trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication/User/Hash.pm 2007-10-25 00:11:07 UTC (rev 7057)
+++ trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication/User/Hash.pm 2007-10-25 16:14:43 UTC (rev 7058)
@@ -1,9 +1,10 @@
package Catalyst::Plugin::Authentication::User::Hash;
-use base qw/Catalyst::Plugin::Authentication::User/;
use strict;
use warnings;
+use base qw/Catalyst::Plugin::Authentication::User/;
+
sub new {
my $class = shift;
@@ -123,36 +124,32 @@
=head1 METHODS
-=over 4
+=head2 new( @pairs )
-=item new @pairs
-
Create a new object with the key-value-pairs listed in the arg list.
-=item supports
+=head2 supports( )
Checks for existence of keys that correspond with features.
-=item for_session
+=head2 for_session( )
Just returns $self, expecting it to be serializable.
-=item from_session
+=head2 from_session( )
Just passes returns the unserialized object, hoping it's intact.
-=item AUTOLOAD
+=head2 AUTOLOAD( )
Accessor for the key whose name is the method.
-=item id
+=head2 id( )
-=item store
+=head2 store( )
Accessors that override superclass's dying virtual methods.
-=back
-
=head1 SEE ALSO
L<Hash::AsObject>
Modified: trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication/User.pm
===================================================================
--- trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication/User.pm 2007-10-25 00:11:07 UTC (rev 7057)
+++ trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication/User.pm 2007-10-25 16:14:43 UTC (rev 7058)
@@ -93,25 +93,18 @@
=head1 METHODS
-=over 4
+=head2 id( )
-=item id
-
A unique ID by which a user can be retrieved from the store.
-=item store
+=head2 store( )
Should return a class name that can be used to refetch the user using it's
ID.
-=item supports
+=head2 supports( )
An introspection method used to determine what features a user object has, to support credential and authorization plugins.
-=item
-
-=back
-
=cut
-
Modified: trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication.pm
===================================================================
--- trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication.pm 2007-10-25 00:11:07 UTC (rev 7057)
+++ trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication.pm 2007-10-25 16:14:43 UTC (rev 7058)
@@ -450,7 +450,8 @@
Configuration of the Catalyst::Plugin::Authentication framework is done in
terms of realms. In simplest terms, a realm is a pairing of a Credential
-verifier and a User storage (Store) backend.
+verifier and a User storage (Store) backend. As of version 0.10003, realms are
+now objects that you can create and customize.
An application can have any number of Realms, each of which operates
independant of the others. Each realm has a name, which is used to identify it
@@ -704,6 +705,9 @@
The only rule here is that there must be at least one. A realm consists of a
name, which is used to reference the realm, a credential and a store.
+You can also specify as realm class to instantiate instead of the default
+L<Catalyst::Plugin::Authentication::Realm> class.
+
Each realm config contains two hashes, one called 'credential' and one called
'store', each of which provide configuration details to the respective modules.
The contents of these hashes is specific to the module being used, with the
@@ -718,25 +722,21 @@
classname 'B<storename>' is expanded to:
Catalyst::Plugin::Authentication::Store::B<storename>.
-
=back
-
=head1 METHODS
-=over 4
+=head2 authenticate( $userinfo, $realm )
-=item authenticate( $userinfo, $realm )
-
Attempts to authenticate the user using the information in the $userinfo hash
reference using the realm $realm. $realm may be omitted, in which case the
default realm is checked.
-=item user
+=head2 user( )
Returns the currently logged in user or undef if there is none.
-=item user_exists
+=head2 user_exists( )
Returns true if a user is logged in right now. The difference between
user_exists and user is that user_exists will return true if a user is logged
@@ -744,22 +744,20 @@
need to know if the user is logged in, depending on the storage mechanism this
can be much more efficient.
-=item user_in_realm ( $realm )
+=head2 user_in_realm( $realm )
Works like user_exists, except that it only returns true if a user is both
logged in right now and was retrieved from the realm provided.
-=item logout
+=head2 logout( )
Logs the user out, Deletes the currently logged in user from $c->user and the session.
-=item find_user( $userinfo, $realm )
+=head2 find_user( $userinfo, $realm )
Fetch a particular users details, matching the provided user info, from the realm
specified in $realm.
-=back
-
=head1 INTERNAL METHODS
These methods are for Catalyst::Plugin::Authentication B<INTERNAL USE> only.
@@ -768,43 +766,41 @@
to fix / rewrite your code when things change. They are documented here only
for reference.
-=over 4
+=head2 set_authenticated( $user, $realmname )
-=item set_authenticated ( $user, $realmname )
-
Marks a user as authenticated. This is called from within the authenticate
routine when a credential returns a user. $realmname defaults to 'default'
-=item auth_restore_user ( $user, $realmname )
+=head2 auth_restore_user( $user, $realmname )
Used to restore a user from the session. In most cases this is called without
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.
-=item save_user_in_session ( $user, $realmname )
+=head2 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.
-=item auth_realms
+=head2 auth_realms( )
Returns a hashref containing realmname -> realm instance pairs. Realm
instances contain an instantiated store and credential object as the 'store'
and 'credential' elements, respectively
-=item get_auth_realm ( $realmname )
+=head2 get_auth_realm( $realmname )
Retrieves the realm instance for the realmname provided.
-=item
-
-=back
-
=head1 SEE ALSO
This list might not be up to date. Below are modules known to work with the updated
API of 0.10 and are therefore compatible with realms.
+=head2 Realms
+
+L<Catalyst::Plugin::Authentication::Realm>
+
=head2 User Storage Backends
L<Catalyst::Plugin::Authentication::Store::Minimal>,
@@ -872,16 +868,14 @@
functionality or any of the methods described above. These are for reference
purposes only.
-=over 4
+=head2 login( )
-=item login
-
This method is used to initiate authentication and user retrieval. Technically
this is part of the old Password credential module and it still resides in the
L<Password|Catalyst::Plugin::Authentication::Credential::Password> class. It is
included here for reference only.
-=item default_auth_store
+=head2 default_auth_store( )
Return the store whose name is 'default'.
@@ -894,26 +888,22 @@
Sets the default store to
L<Catalyst::Plugin::Authentication::Store::Minimal>.
-=item get_auth_store $name
+=head2 get_auth_store( $name )
Return the store whose name is $name.
-=item get_auth_store_name $store
+=head2 get_auth_store_name( $store )
Return the name of the store $store.
-=item auth_stores
+=head2 auth_stores( )
A hash keyed by name, with the stores registered in the app.
-=item register_auth_stores %stores_by_name
+=head2 register_auth_stores( %stores_by_name )
Register stores into the application.
-=back
-
-
-
=head1 AUTHORS
Yuval Kogman, C<nothingmuch at woobling.org>
@@ -924,7 +914,6 @@
David Kamholz
-
=head1 COPYRIGHT & LICENSE
Copyright (c) 2005 the aforementioned authors. All rights
More information about the Catalyst-commits
mailing list