Catalyst-Plugin-Authentication
view release on metacpan or search on metacpan
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
0.10003 2007-12-02
- 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
saving into the session.
0.10001 2007-07-17
- updated tests
0.10000 2007-07-11
- Minor updates to work better with compatibility mode
- Producion release
- switch to Module::Install
0.09999_01 2007-02-21
- major changes to the internals of the plugin, to better encapsulate
credentials and stores.
- introduction of 'realms' concept, allowing multiple different
pairs of credential and store in a single application.
0.09 2006-08-01
- be a bit more pedantic about checking values for definedness before
invoking methods on them
0.08 2006-07-29
- factor test applications out to files due to changes in Catalyst::Test
- don't load session at prepare time unless necessary
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 exception of the 'class' element,
which tells the core Authentication module the classname to
instantiate.
The 'class' element follows the standard Catalyst mechanism of class
specification. If a class is prefixed with a +, it is assumed to be
a complete class name. Otherwise it is considered to be a portion of
the class name. For credentials, the classname 'Password', for
example, is expanded to
Catalyst::Authentication::Credential::Password. For stores, the
classname 'storename' is expanded to:
Catalyst::Authentication::Store::storename.
METHODS
$c->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.
Catalyst::Plugin::Session, Catalyst::Plugin::Session::PerUser
DON'T SEE ALSO
This module along with its sub plugins deprecate a great number of other
modules. These include Catalyst::Plugin::Authentication::Simple,
Catalyst::Plugin::Authentication::CDBI.
INCOMPATABILITIES
The realms-based configuration and functionality of the 0.10 update of
Catalyst::Plugin::Authentication required a change in the API used by
credentials and stores. It has a compatibility mode which allows use of
modules that have not yet been updated. This, however, completely mimics
the older api and disables the new realm-based features. In other words
you cannot mix the older credential and store modules with realms, or
realm-based configs. The changes required to update modules are
relatively minor and are covered in
Catalyst::Plugin::Authentication::Internals. We hope that most modules
will move to the compatible list above very quickly.
COMPATIBILITY CONFIGURATION
Until version 0.10008 of this module, you needed to put all the realms
lib/Catalyst/Authentication/Credential/NoPassword.pm view on Meta::CPAN
if ($c->user_exists() and $c->user->username() eq 'root') {
$c->authenticate( {id => c->req->params->{user_id}}, 'nopassword' );
}
}
=head1 DESCRIPTION
This authentication credential checker takes authentication information
(most often a username) and retrieves the user from the store. No validation
of any credentials is done. This is intended for administrative backdoors,
SAML logins and so on when you have identified the new user by other means.
=head1 CONFIGURATION
# example
<Plugin::Authentication>
<nopassword>
<credential>
class = NoPassword
</credential>
lib/Catalyst/Authentication/Realm.pm view on Meta::CPAN
# and rely on it being present. (this avoids per-call checks)
if (!$storeclass->can('find_user')) {
no strict 'refs';
*{"${storeclass}::find_user"} = sub {
my ($self, $info) = @_;
my @rest = @{$info->{rest}} if exists($info->{rest});
$self->get_user($info->{id}, @rest);
};
}
## a little cruft to stay compatible with some poorly written stores / credentials
## we'll remove this soon.
if ($storeclass->can('new')) {
$self->store($storeclass->new($config->{'store'}, $app, $self));
}
else {
$app->log->error("THIS IS DEPRECATED: $storeclass has no new() method - Attempting to use uninstantiated");
$self->store($storeclass);
}
if ($credentialclass->can('new')) {
$self->credential($credentialclass->new($config->{'credential'}, $app, $self));
lib/Catalyst/Authentication/Store.pod view on Meta::CPAN
This is on a per user (not necessarily a per store) basis. To make assumptions
about the store as a whole,
$store->user_supports(qw/password clear/);
is supposed to be the lowest common denominator.
The standardization of these values is to be goverened by the community,
typically defined by the credential verification plugins.
=head2 Stores implying certain credentials
Sometimes a store is agnostic to the credentials (DB storage, for example), but
sometimes it isn't (like an Htpasswd file).
If you are writing a backend that wraps around a module, like
L<Catalyst::Authentication::Store::Htpasswd> wraps around
L<Authen::Htpasswd>, it makes sense to delegate the credential checks.
This particular example caused the following "feature" to be added:
$user->supports(qw/password self_check/);
lib/Catalyst/Authentication/Store/Null.pm view on Meta::CPAN
store => {
class => 'Null',
}
}
}
});
=head1 DESCRIPTION
The Null store is a transparent store where any supplied user data is
accepted. This is mainly useful for remotely authenticating credentials
(e.g. TypeKey, OpenID) which may not be tied to any local storage. It also
helps facilitate integration with the Session plugin.
=head1 METHODS
=head2 new( )
Creates a new instance of the store.
=head2 for_session( )
lib/Catalyst/Plugin/Authentication.pm view on Meta::CPAN
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
exception of the 'class' element, which tells the core Authentication module the
classname to instantiate.
The 'class' element follows the standard Catalyst mechanism of class
specification. If a class is prefixed with a +, it is assumed to be a complete
class name. Otherwise it is considered to be a portion of the class name. For
credentials, the classname 'B<Password>', for example, is expanded to
Catalyst::Authentication::Credential::B<Password>. For stores, the
classname 'B<storename>' is expanded to:
Catalyst::Authentication::Store::B<storename>.
=back
=head1 METHODS
=head2 $c->authenticate( $userinfo [, $realm ])
lib/Catalyst/Plugin/Authentication.pm view on Meta::CPAN
=head1 DON'T SEE ALSO
This module along with its sub plugins deprecate a great number of other
modules. These include L<Catalyst::Plugin::Authentication::Simple>,
L<Catalyst::Plugin::Authentication::CDBI>.
=head1 INCOMPATABILITIES
The realms-based configuration and functionality of the 0.10 update
of L<Catalyst::Plugin::Authentication> required a change in the API used by
credentials and stores. It has a compatibility mode which allows use of
modules that have not yet been updated. This, however, completely mimics the
older api and disables the new realm-based features. In other words you cannot
mix the older credential and store modules with realms, or realm-based
configs. The changes required to update modules are relatively minor and are
covered in L<Catalyst::Plugin::Authentication::Internals>. We hope that most
modules will move to the compatible list above very quickly.
=head1 COMPATIBILITY CONFIGURATION
Until version 0.10008 of this module, you needed to put all the
lib/Catalyst/Plugin/Authentication/Credential/Password.pm view on Meta::CPAN
}
else {
$c->log->debug(
"Failed to authenticate user '$user'. Reason: 'Incorrect password'")
if $c->debug;
return;
}
}
## also deprecated. Here for compatibility with older credentials which do not inherit from C::P::A::Password
sub _check_password {
my ( $c, $user, $password ) = @_;
if ( $user->supports(qw/password clear/) ) {
return $user->password eq $password;
}
elsif ( $user->supports(qw/password crypted/) ) {
my $crypted = $user->crypted_password;
return $crypted eq crypt( $password, $crypted );
}
lib/Catalyst/Plugin/Authentication/Internals.pod view on Meta::CPAN
L<Catalyst::Plugin::Authentication|Catalyst::Plugin::Authentication> provides
a standard authentication interface to application developers using the
Catalyst framework. It is designed to allow application developers to use
various methods of user storage and credential verification. It is also
designed to provide for minimal change to the application when switching
between different storage and credential verification methods.
While L<Catalyst::Plugin::Authentication|Catalyst::Plugin::Authentication>
provides the interface to the application developer, the actual work of
verifying the credentials and retrieving users is delegated to separate
modules. These modules are called B<Credentials> and storage backends, or
B<Stores>, respectively. For authentication to function there must be at least
one credential and one store. A pairing of a store and a credential
is referred to as a B<Realm>. There may be any number of realms defined for an
application, though most applications will not require more than one or two.
The details of using this module can be found in the
L<Catalyst::Plugin::Authentication|Catalyst::Plugin::Authentication>
documentation.
lib/Catalyst/Plugin/Authentication/Internals.pod view on Meta::CPAN
2) Credential's authenticate() method called with authinfo and realm object for current realm
=over 4
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
3) User object stored in session
=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 realm
object's persist_user() method. The persist_user() routine by
lib/Catalyst/Plugin/Authentication/Internals.pod view on Meta::CPAN
More detailed information about these processes is below.
=head2 INITIALIZATION
When the authentication module is loaded, it reads it's configuration to
determine the realms to set up for the application and which realm is to be
the default. For each realm defined in the application's config,
L<Catalyst::Plugin::Authentication|Catalyst::Plugin::Authentication>
instantiates both a new credential object and a new store object. See below
for the details of how credentials and stores are instantiated.
B<NOTE>: The instances created will remain active throughout the entire
lifetime of the application, and so should be relatively lightweight.
Care should be taken to ensure that they do not grow, or retain
information per request, because they will be involved in each
authentication request and could therefore substantially
hurt memory consumption over time.
=head2 AUTHENTICATION
When C<$c-E<gt>authenticate()> is called from within an application, the
objects created in the initialization process come into play.
C<$c-E<gt>authenticate()> takes two arguments. The first is a hash reference
containing all the information available about the user. This will be used to
locate the user in the store and verify the user's credentials. The second
argument is the realm to authenticate against. If the second argument is
omitted, the default realm is assumed.
The main authentication module then locates the credential and store objects
for the realm specified and calls the credential object's C<authenticate()>
method. It provides three arguments, first the application object, or C<$c>,
then a reference to the store object, and finally the hashref provided in the
C<$c-E<gt>authenticate> call. The main authentication module expects the
return value to be a reference to a user object upon successful
authentication. If it receives anything aside from a reference, it is
lib/Catalyst/Plugin/Authentication/Internals.pod view on Meta::CPAN
=item from_session( $c, $frozenuser )
This method is called whenever a user is being restored from the session.
C<$frozenuser> contains the information that was stored in the session for the user.
This will under normal circumstances be the exact data your store returned from
the previous call to C<for_session()>. C<from_session()> should return a valid
user object.
=item user_supports( $feature, ... )
This method allows credentials and other objects to inquire as to what the
underlying user object is capable of. This is pretty-well free-form and the
main purpose is to allow graceful integration with credentials and
applications that may provide advanced functionality based on whether the
underlying user object can do certain things. In most cases you will want to
pass this directly to the underlying user class' C<supports> method. Note that
this is used as a B<class> method against the user class and therefore must
be able to function without an instantiated user object.
=back
=head3 OPTIONAL STORE METHODS
( run in 0.317 second using v1.01-cache-2.11-cpan-4d50c553e7e )