X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FPlugin%2FAuthentication%2FCredential%2FPassword.pm;h=0a161fc8df20d81f11e639b6ca792f3945f2ab11;hb=89505ffb6e0211be9d995df31f7b7de3913e3922;hp=d98b70c62e8d697387e9ccd87dd827948c24421d;hpb=30e90c6f368296c03308202246e25abc8e565690;p=catagits%2FCatalyst-Plugin-Authentication.git diff --git a/lib/Catalyst/Plugin/Authentication/Credential/Password.pm b/lib/Catalyst/Plugin/Authentication/Credential/Password.pm index d98b70c..0a161fc 100644 --- a/lib/Catalyst/Plugin/Authentication/Credential/Password.pm +++ b/lib/Catalyst/Plugin/Authentication/Credential/Password.pm @@ -200,169 +200,152 @@ with a password. 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: - -=over 4 - -=item clear text password - -If the user has clear a clear text password it will be compared directly. - -=item crypted password +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. -If UNIX crypt hashed passwords are supported, they will be compared using -perl's builtin C function. +=head1 CONFIGURATION -=item hashed 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 object supports hashed passwords, they will be used in conjunction -with L. - -=back -=head1 METHODS +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. -=over 4 +=over 4 -=item login $username, $password +=item class -Try to log a user in. +The classname used for Credential. This is part of +L 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'. -C<$username> can be a string (e.g. retrieved from a form) or an object. -If the object is a L it will be used -as is. Otherwise C<< $c->get_user >> is used to retrieve it. +=item password_field -C<$password> is a string. +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'); -If C<$username> or C<$password> are not provided, the query parameters -C, C, C and C, C, C will -be tried instead. +=item password_type -=back +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: -=head1 RELATED USAGE +=over 8 -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. +=item clear -The current user can be logged out again by calling the C<< $c->logout >> -method. +The password in user is in clear text and will be compared directly. -=head1 SUPPORTING THIS PLUGIN +=item self_check -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 method in one or many of the -following ways: +This option indicates that the password should be passed to the check_password() +routine on the user object returned from the store. -=head2 Clear Text Passwords +=item crypted -Predicate: +The password in user is in UNIX crypt hashed format. - $user->supported_features(qw/password clear/); +=item salted_hash -Expected methods: +The password in user is in salted hash format, and will be validated +using L. If this password type is selected, you should +also provide the B config element to define the salt length. -=over 4 - -=item password - -Returns the user's clear text password as a string to be compared with C. - -=back - -=head2 Crypted Passwords - -Predicate: - - $user->supported_features(qw/password crypted/); - -Expected methods: - -=over 4 +=item hashed -=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 +If the user object supports hashed passwords, they will be used in conjunction +with L. The following config elements affect the hashed configuration: -=item hashed_password +=over 8 -Return's the hash of the user's password as B. +=item password_hash_type -=item hash_algorithm +The hash type used, passed directly to L. -Returns a string suitable for feeding into L. +=item password_pre_salt -=item password_pre_salt +Any pre-salt data to be passed to L before processing the password. =item password_post_salt -Returns a string to be hashed before/after the user's password. Typically only -a pre-salt is used. +Any post-salt data to be passed to L after processing the password. =back -=head2 Crypt::SaltedHash Passwords - -Predicate: - - $user->supported_features(qw/password salted_hash/); +=back -Expected methods: +=back -=over 4 +=head1 USAGE -=item hashed_password +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 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: -Returns the hash of the user's password as returned from L->generate. + if ($c->authenticate({ username => $username, + password => $password} )) { + # authentication successful + } else { + # authentication failed + } -=back +=head1 METHODS -Optional methods: +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 for all credential modules. =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 - -=cut +=item 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