[Catalyst-commits] r6548 - in trunk/Catalyst-Plugin-Authentication:
. lib/Catalyst/Plugin/Authentication/Credential
matthewt at dev.catalyst.perl.org
matthewt at dev.catalyst.perl.org
Tue Jul 17 17:58:03 GMT 2007
Author: matthewt
Date: 2007-07-17 17:58:03 +0100 (Tue, 17 Jul 2007)
New Revision: 6548
Modified:
trunk/Catalyst-Plugin-Authentication/
trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication/Credential/Password.pm
Log:
r33947 at cain (orig r5497): jayk | 2006-11-12 06:04:54 +0000
Updating Documentation on Password
Property changes on: trunk/Catalyst-Plugin-Authentication
___________________________________________________________________
Name: svk:merge
- 4ad37cd2-5fec-0310-835f-b3785c72a374:/branches/Catalyst-Plugin-Authentication:5495
+ 4ad37cd2-5fec-0310-835f-b3785c72a374:/branches/Catalyst-Plugin-Authentication:5497
Modified: trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication/Credential/Password.pm
===================================================================
--- trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication/Credential/Password.pm 2007-07-17 16:58:00 UTC (rev 6547)
+++ trunk/Catalyst-Plugin-Authentication/lib/Catalyst/Plugin/Authentication/Credential/Password.pm 2007-07-17 16:58:03 UTC (rev 6548)
@@ -200,169 +200,152 @@
use Catalyst qw/
Authentication
- Authentication::Store::Foo
- Authentication::Credential::Password
/;
package MyApp::Controller::Auth;
- # *** NOTE ***
- # if you place an action named 'login' in your application's root (as
- # opposed to inside a controller) the following snippet will recurse,
- # giving you lots of grief.
- # never name actions in the root controller after plugin methods - use
- # controllers and : Global instead.
-
sub login : Local {
my ( $self, $c ) = @_;
- $c->login( $c->req->param('username'), $c->req->param('password') );
+ $c->authenticate( { username => $c->req->param('username'),
+ password => $c->req->param('password') });
}
=head1 DESCRIPTION
-This authentication credential checker takes a username (or userid) and a
-password, and tries various methods of comparing a password based on what
-the chosen store's user objects support:
+This authentication credential checker takes authentication information
+(most often a username) and a password, and attempts to validate the password
+provided against the user retrieved from the store.
-=over 4
+=head1 CONFIGURATION
-=item clear text password
+ # example
+ __PACKAGE__->config->{authentication} =
+ {
+ default_realm => 'members',
+ realms => {
+ members => {
+
+ credential => {
+ class => 'Password',
+ password_field => 'password',
+ password_type => 'hashed',
+ password_hash_type => 'SHA-1'
+ },
+ ...
-If the user has clear a clear text password it will be compared directly.
-=item crypted password
+The password module is capable of working with several different password
+encryption/hashing algorithms. The one the module uses is determined by the
+credential configuration.
-If UNIX crypt hashed passwords are supported, they will be compared using
-perl's builtin C<crypt> function.
+=over 4
-=item hashed password
+=item class
-If the user object supports hashed passwords, they will be used in conjunction
-with L<Digest>.
+The classname used for Credential. This is part of
+L<Catalyst::Plugin::Authentication> and is the method by which
+Catalyst::Plugin::Authentication::Credential::Password is loaded as the
+credential validator. For this module to be used, this must be set to
+'Password'.
-=back
+=item password_field
-=head1 METHODS
+The field in the user object that contains the password. This will vary
+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');
-=over 4
+=item password_type
-=item login $username, $password
+This sets the password type. Often passwords are stored in crypted or hashed
+formats. In order for the password module to verify the plaintext password
+passed in, it must be told what format the password will be in when it is retreived
+from the user object. The supported options are:
-Try to log a user in.
+=over 8
-C<$username> can be a string (e.g. retrieved from a form) or an object.
-If the object is a L<Catalyst::Plugin::Authentication::User> it will be used
-as is. Otherwise C<< $c->get_user >> is used to retrieve it.
+=item clear
-C<$password> is a string.
+The password in user is in clear text and will be compared directly.
-If C<$username> or C<$password> are not provided, the query parameters
-C<login>, C<user>, C<username> and C<password>, C<passwd>, C<pass> will
-be tried instead.
+=item self_check
-=back
+This option indicates that the password should be passed to the check_password()
+routine on the user object returned from the store.
-=head1 RELATED USAGE
+=item crypted
-After the user is logged in, the user object for the current logged in user
-can be retrieved from the context using the C<< $c->user >> method.
+The password in user is in UNIX crypt hashed format.
-The current user can be logged out again by calling the C<< $c->logout >>
-method.
+=item salted_hash
-=head1 SUPPORTING THIS PLUGIN
+The password in user is in salted hash format, and will be validated
+using L<Crypt::SaltedHash>. If this password type is selected, you should
+also provide the B<password_salt_len> config element to define the salt length.
-For a User class to support credential verification using this plugin, it
-needs to indicate what sort of password a given user supports
-by implementing the C<supported_features> method in one or many of the
-following ways:
+=item hashed
-=head2 Clear Text Passwords
+If the user object supports hashed passwords, they will be used in conjunction
+with L<Digest>. The following config elements affect the hashed configuration:
-Predicate:
+=over 8
- $user->supported_features(qw/password clear/);
+=item password_hash_type
-Expected methods:
+The hash type used, passed directly to L<Digest/new>.
-=over 4
+=item password_pre_salt
-=item password
+Any pre-salt data to be passed to L<Digest/add> before processing the password.
-Returns the user's clear text password as a string to be compared with C<eq>.
+=item password_post_salt
+Any post-salt data to be passed to L<Digest/add> after processing the password.
+
=back
-=head2 Crypted Passwords
-
-Predicate:
-
- $user->supported_features(qw/password crypted/);
-
-Expected methods:
-
-=over 4
-
-=item crypted_password
-
-Return's the user's crypted password as a string, with the salt as the first two chars.
-
=back
-=head2 Hashed Passwords
-
-Predicate:
-
- $user->supported_features(qw/password hashed/);
-
-Expected methods:
-
-=over 4
-
-=item hashed_password
-
-Return's the hash of the user's password as B<binary>.
-
-=item hash_algorithm
-
-Returns a string suitable for feeding into L<Digest/new>.
-
-=item password_pre_salt
-
-=item password_post_salt
-
-Returns a string to be hashed before/after the user's password. Typically only
-a pre-salt is used.
-
=back
-=head2 Crypt::SaltedHash Passwords
+=head1 USAGE
-Predicate:
+The Password credential module is very simple to use. Once configured as indicated
+above, authenticating using this module is simply a matter of calling $c->authenticate()
+with an authinfo hashref that includes the B<password> element. The password element should
+contain the password supplied by the user to be authenticated, in clear text. The other
+information supplied in the auth hash is ignored by the Password module, and simply passed
+to the auth store to be used to retrieve the user. An example call follows:
- $user->supported_features(qw/password salted_hash/);
+ if ($c->authenticate({ username => $username,
+ password => $password} )) {
+ # authentication successful
+ } else {
+ # authentication failed
+ }
-Expected methods:
+=head1 METHODS
-=over 4
+There are no publicly exported routines in the Password module (or indeed in
+most credential modules.) However, below is a description of the routines
+required by L<Catalyst::Plugin::Authentication> for all credential modules.
-=item hashed_password
-
-Returns the hash of the user's password as returned from L<Crypt-SaltedHash>->generate.
-
-=back
-
-Optional methods:
-
=over 4
-=item password_salt_len
+=item new ( $config, $app )
-Returns the length of salt used to generate the salted hash.
+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
+plugin setup phase, which is before the application specific controllers are
+loaded. The practical upshot of this is that things like $c->model(...) will
+not function as expected.
-=back
+=item authenticate ( $authinfo, $c )
-=cut
+Try to log a user in, receives a hashref containing authentication information
+as the first argument, and the current context as the second.
-
+=back
More information about the Catalyst-commits
mailing list