-#!/usr/bin/perl
-
package Catalyst::Plugin::Authentication;
use base qw/Class::Accessor::Fast Class::Data::Inheritable/;
BEGIN {
__PACKAGE__->mk_accessors(qw/_user/);
- __PACKAGE__->mk_classdata($_) for qw/_auth_realms/;
}
use strict;
# constant->import(have_want => eval { require Want });
#}
-our $VERSION = "0.10";
+our $VERSION = "0.10002";
sub set_authenticated {
my ( $c, $user, $realmname ) = @_;
and $c->config->{authentication}{use_session}
and $user->supports("session") )
{
- $c->save_user_in_session($realmname, $user);
+ $c->save_user_in_session($user, $realmname);
}
- $user->_set_auth_realm($realmname);
+ $user->auth_realm($realmname);
$c->NEXT::set_authenticated($user, $realmname);
}
-sub _should_save_user_in_session {
- my ( $c, $user ) = @_;
-
- $c->_auth_sessions_supported
- and $c->config->{authentication}{use_session}
- and $user->supports("session");
-}
-
-sub _should_load_user_from_session {
- my ( $c, $user ) = @_;
-
- $c->_auth_sessions_supported
- and $c->config->{authentication}{use_session}
- and $c->session_is_valid;
-}
-
-sub _auth_sessions_supported {
- my $c = shift;
- $c->isa("Catalyst::Plugin::Session");
-}
-
sub user {
my $c = shift;
return $c->_user(@_);
}
- if ( defined(my $user = $c->_user) ) {
- return $user;
+ if ( defined($c->_user) ) {
+ return $c->_user;
} else {
return $c->auth_restore_user;
}
return defined($c->_user) || defined($c->_user_in_session);
}
+# works like user_exists - except only returns true if user
+# exists AND is in the realm requested.
+sub user_in_realm {
+ my ($c, $realmname) = @_;
+
+ 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;
+ }
+}
sub save_user_in_session {
- my ( $c, $realmname, $user ) = @_;
+ my ( $c, $user, $realmname ) = @_;
$c->session->{__user_realm} = $realmname;
- # we want to ask the backend for a user prepared for the session.
+ # we want to ask the store for a user prepared for the session.
# but older modules split this functionality between the user and the
- # backend. We try the store first. If not, we use the old method.
+ # store. We try the store first. If not, we use the old method.
my $realm = $c->get_auth_realm($realmname);
if ($realm->{'store'}->can('for_session')) {
$c->session->{__user} = $realm->{'store'}->for_session($c, $user);
sub _user_in_session {
my $c = shift;
- return unless $c->_should_load_user_from_session;
+ return unless
+ $c->isa("Catalyst::Plugin::Session")
+ and $c->config->{authentication}{use_session}
+ and $c->session_is_valid;
return $c->session->{__user};
}
-sub _store_in_session {
- my $c = shift;
-
- # we don't need verification, it's only called if _user_in_session returned something useful
-
- return $c->session->{__user_store};
-}
-
sub auth_restore_user {
my ( $c, $frozen_user, $realmname ) = @_;
$c->_user( my $user = $realm->{'store'}->from_session( $c, $frozen_user ) );
# this sets the realm the user originated in.
- $user->_set_auth_realm($realmname);
+ $user->auth_realm($realmname);
+
return $user;
}
# we can't actually do our setup in setup because the model has not yet been loaded.
# So we have to trigger off of setup_finished. :-(
sub setup {
- my $c = shift;
+ my $app = shift;
- $c->_authentication_initialize();
- $c->NEXT::setup(@_);
+ $app->_authentication_initialize();
+ $app->NEXT::setup(@_);
}
## the actual initialization routine. whee.
sub _authentication_initialize {
- my $c = shift;
+ my $app = shift;
- if ($c->_auth_realms) { return };
-
- my $cfg = $c->config->{'authentication'} || {};
+ ## let's avoid recreating / configuring everything if we have already done it, eh?
+ if ($app->can('_auth_realms')) { return };
- %$cfg = (
- use_session => 1,
- %$cfg,
- );
+ ## make classdata where it is used.
+ $app->mk_classdata( '_auth_realms' => {});
+
+ my $cfg = $app->config->{'authentication'} ||= {};
- my $realmhash = {};
- $c->_auth_realms($realmhash);
+ $cfg->{use_session} = 1;
- ## BACKWARDS COMPATIBILITY - if realm is not defined - then we are probably dealing
- ## with an old-school config. The only caveat here is that we must add a classname
if (exists($cfg->{'realms'})) {
-
foreach my $realm (keys %{$cfg->{'realms'}}) {
- $c->setup_auth_realm($realm, $cfg->{'realms'}{$realm});
+ $app->setup_auth_realm($realm, $cfg->{'realms'}{$realm});
}
-
# 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'}) && !$c->get_auth_realm('default')) {
- $c->set_default_auth_realm($cfg->{'default_realm'});
+ if (exists($cfg->{'default_realm'}) && !$app->get_auth_realm('default')) {
+ $app->_set_default_auth_realm($cfg->{'default_realm'});
}
} else {
+
+ ## BACKWARDS COMPATIBILITY - if realms is not defined - then we are probably dealing
+ ## with an old-school config. The only caveat here is that we must add a classname
+
+ ## also - we have to treat {store} as {stores}{default} - because
+ ## while it is not a clear as a valid config in the docs, it
+ ## is functional with the old api. Whee!
+ if (exists($cfg->{'store'}) && !exists($cfg->{'stores'}{'default'})) {
+ $cfg->{'stores'}{'default'} = $cfg->{'store'};
+ }
+
foreach my $storename (keys %{$cfg->{'stores'}}) {
my $realmcfg = {
- store => $cfg->{'stores'}{$storename},
+ store => { class => $cfg->{'stores'}{$storename} },
};
- $c->setup_auth_realm($storename, $realmcfg);
+ $app->setup_auth_realm($storename, $realmcfg);
}
}
}
-
# set up realmname.
sub setup_auth_realm {
my ($app, $realmname, $config) = @_;
- $app->log->debug("Setting up $realmname");
+ $app->log->debug("Setting up auth realm $realmname") if $app->debug;
if (!exists($config->{'store'}{'class'})) {
Carp::croak "Couldn't setup the authentication realm named '$realmname', no class defined";
}
my $storeclass = $config->{'store'}{'class'};
## follow catalyst class naming - a + prefix means a fully qualified class, otherwise it's
- ## taken to mean C::P::A::Store::(specifiedclass)::Backend
+ ## taken to mean C::P::A::Store::(specifiedclass)
if ($storeclass !~ /^\+(.*)$/ ) {
- $storeclass = "Catalyst::Plugin::Authentication::Store::${storeclass}::Backend";
+ $storeclass = "Catalyst::Plugin::Authentication::Store::${storeclass}";
} else {
$storeclass = $1;
}
# a little niceness - since most systems seem to use the password credential class,
# if no credential class is specified we use password.
- $config->{credential}{class} ||= "Catalyst::Plugin::Authentication::Credential::Password";
+ $config->{credential}{class} ||= '+Catalyst::Plugin::Authentication::Credential::Password';
my $credentialclass = $config->{'credential'}{'class'};
};
}
- $app->auth_realms->{$realmname}{'store'} = $storeclass->new($config->{'store'}, $app);
+ ## a little cruft to stay compatible with some poorly written stores / credentials
+ ## we'll remove this soon.
+ if ($storeclass->can('new')) {
+ $app->auth_realms->{$realmname}{'store'} = $storeclass->new($config->{'store'}, $app);
+ } else {
+ $app->log->error("THIS IS DEPRECATED: $storeclass has no new() method - Attempting to use uninstantiated");
+ $app->auth_realms->{$realmname}{'store'} = $storeclass;
+ }
if ($credentialclass->can('new')) {
$app->auth_realms->{$realmname}{'credential'} = $credentialclass->new($config->{'credential'}, $app);
} else {
- # if the credential class is not actually a class - has no 'new' operator, we wrap it,
- # once again - to allow our code to be simple at runtime and allow non-OO packages to function.
- my $wrapperclass = 'Catalyst::Plugin::Authentication::Credential::Wrapper';
- Catalyst::Utils::ensure_class_loaded( $wrapperclass );
- $app->auth_realms->{$realmname}{'credential'} = $wrapperclass->new($config->{'credential'}, $app);
+ $app->log->error("THIS IS DEPRECATED: $credentialclass has no new() method - Attempting to use uninstantiated");
+ $app->auth_realms->{$realmname}{'credential'} = $credentialclass;
}
}
return $app->auth_realms->{$realmname};
}
-sub set_default_auth_realm {
+
+# Very internal method. Vital Valuable Urgent, Do not touch on pain of death.
+# Using this method just assigns the default realm to be the value associated
+# with the realmname provided. It WILL overwrite any real realm called 'default'
+# so can be very confusing if used improperly. It's used properly already.
+# Translation: don't use it.
+sub _set_default_auth_realm {
my ($app, $realmname) = @_;
if (exists($app->auth_realms->{$realmname})) {
my $realm = $app->get_auth_realm($realmname);
+ ## note to self - make authenticate throw an exception if realm is invalid.
+
if ($realm && exists($realm->{'credential'})) {
my $user = $realm->{'credential'}->authenticate($app, $realm->{store}, $userinfo);
- if ($user) {
+ if (ref($user)) {
$app->set_authenticated($user, $realmname);
return $user;
}
return $c->find_user( {'id' => $uid, 'rest'=>\@rest }, 'default' );
}
-##
+
## this should only be called when using old-style authentication plugins. IF this gets
## called in a new-style config - it will OVERWRITE the store of your default realm. Don't do it.
## also - this is a partial setup - because no credential is instantiated... in other words it ONLY
if ( my $new = shift ) {
$self->auth_realms->{'default'}{'store'} = $new;
- my $storeclass = ref($new);
+
+ my $storeclass;
+ if (ref($new)) {
+ $storeclass = ref($new);
+ } else {
+ $storeclass = $new;
+ }
# BACKWARDS COMPATIBILITY - if the store class does not define find_user, we define it in terms
# of get_user and add it to the class. this is because the auth routines use find_user,
my %hash = ( 'default' => $self->get_auth_realm('default')->{'store'});
}
-
-
-
-
-
__PACKAGE__;
__END__
/;
# later on ...
- $c->authenticate({ username => 'myusername', password => 'mypassword' });
+ $c->authenticate({ username => 'myusername',
+ password => 'mypassword' });
my $age = $c->user->get('age');
$c->logout;
store the user information, and can store any amount of data related to the
user. Credentials are used to verify users, using information from the store,
given data from the frontend. A Credential and a Store are paired to form a
-'Realm'. A Catalyst applicaiton using the authentication framework must have
-at least one realm, and may have multiple.
+'Realm'. A Catalyst application using the authentication framework must have
+at least one realm, and may have several.
To implement authentication in a Catalyst application you need to add this
module, and specify at least one realm in the configuration.
Authentication data can also be stored in a session, if the application
is using the L<Catalyst::Plugin::Session> module.
+B<NOTE> in version 0.10 of this module, the interface to this module changed.
+Please see L</COMPATIBILITY ROUTINES> for more information.
+
=head1 INTRODUCTION
=head2 The Authentication/Authorization Process
is (or isn't) allowed to do. For example, say your users are split into two
main groups - regular users and administrators. You want to verify that the
currently logged in user is indeed an administrator before performing the
-actions in an administrative part of your application. These decisionsmay be
+actions in an administrative part of your application. These decisions may be
made within your application code using just the information available after
authentication, or it may be facilitated by a number of plugins.
=head3 Storage Backends
-The authentication data also identifies a user, and the Storage Backend modules
+The authentication data also identifies a user, and the Storage backend modules
use this data to locate and return a standardized object-oriented
representation of a user.
/;
__PACKAGE__->config->{authentication} =
- {
- default_realm => 'members',
- realms => {
- members => {
- credential => {
- class => 'Password'
- },
- store => {
- class => 'Minimal',
- users = {
- bob => {
- password => "s00p3r",
- editor => 'yes',
- roles => [qw/edit delete/],
- },
- william => {
- password => "s3cr3t",
- roles => [qw/comment/],
- }
- }
- }
- }
- }
- };
+ {
+ default_realm => 'members',
+ realms => {
+ members => {
+ credential => {
+ class => 'Password',
+ password_field => 'password',
+ password_type => 'clear'
+ },
+ store => {
+ class => 'Minimal',
+ users = {
+ bob => {
+ password => "s00p3r",
+ editor => 'yes',
+ roles => [qw/edit delete/],
+ },
+ william => {
+ password => "s3cr3t",
+ roles => [qw/comment/],
+ }
+ }
+ }
+ }
+ }
+ };
This tells the authentication plugin what realms are available, which
}
This code should be very readable. If all the necessary fields are supplied,
-call the L<Catalyst::Plugin::Authentication/authenticate> method in the
-controller. If it succeeds the user is logged in.
+call the "authenticate" method from the controller. If it succeeds the
+user is logged in.
The credential verifier will attempt to retrieve the user whose details match
the authentication information provided to $c->authenticate(). Once it fetches
} ...
-Now suppose we want to restrict the ability to edit to a user with 'edit'
-in it's roles list.
+Now suppose we want to restrict the ability to edit to a user with an
+'editor' value of yes.
The restricted action might look like this:
$c->detach("unauthorized")
unless $c->user_exists
- and $c->user->get('editor') == 'yes';
+ and $c->user->get('editor') eq 'yes';
# do something restricted here
}
-This is somewhat similar to role based access control.
+(Note that if you have multiple realms, you can use $c->user_in_realm('realmname')
+in place of $c->user_exists(); This will essentially perform the same
+verification as user_exists, with the added requirement that if there is a
+user, it must have come from the realm specified.)
+
+The above example is somewhat similar to role based access control.
L<Catalyst::Plugin::Authentication::Store::Minimal> treats the roles field as
an array of role names. Let's leverage this. Add the role authorization
plugin:
realms => {
members => {
credential => {
- class => 'Password'
+ class => 'Password',
+ password_field => 'password',
+ password_type => 'clear'
},
store => {
class => 'DBIx::Class',
The authentication system works behind the scenes to load your data from the
new source. The rest of your application is completely unchanged.
-=head1 METHODS
-
-=over 4
-
-
-=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
-
-Returns the currently logged in user or undef if there is none.
-
-=item 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
-in, even if it has not been retrieved from the storage backend. If you only
-need to know if the user is logged in, depending on the storage mechanism this
-can be much more efficient.
-
-=item logout
-
-Logs the user out, Deletes the currently logged in user from $c->user and the session.
-
-=item find_user( $userinfo, $realm )
-
-Fetch a particular users details, matching the provided user info, from the realm
-specified in $realm.
-
-=back
=head1 CONFIGURATION
realms => {
members => {
credential => {
- class => 'Password'
+ class => 'Password',
+ password_field => 'password',
+ password_type => 'clear'
},
store => {
class => 'DBIx::Class',
},
admins => {
credential => {
- class => 'Password'
+ class => 'Password',
+ password_field => 'password',
+ password_type => 'clear'
},
store => {
class => '+MyApp::Authentication::Store::NetAuth',
=item use_session
Whether or not to store the user's logged in state in the session, if the
-application is also using the L<Catalyst::Plugin::Session> plugin. This
+application is also using L<Catalyst::Plugin::Session>. This
value is set to true per default.
=item default_realm
'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 use for that entry.
+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::Plugin::Authentication::Credential::Password. For stores, the
-classname 'storename' is expanded to:
-Catalyst::Plugin::Authentication::Store::storename::Backend.
+credentials, the classname 'B<Password>', for example, is expanded to
+Catalyst::Plugin::Authentication::Credential::B<Password>. For stores, the
+classname 'B<storename>' is expanded to:
+Catalyst::Plugin::Authentication::Store::B<storename>.
=back
- ... this is where the documentation fairy got distracted and moved on to other things ...
+
+=head1 METHODS
+
+=over 4
+
+=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
+
+Returns the currently logged in user or undef if there is none.
+
+=item 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
+in, even if it has not been yet retrieved from the storage backend. If you only
+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 )
+
+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
+
+Logs the user out, Deletes the currently logged in user from $c->user and the session.
+
+=item find_user( $userinfo, $realm )
+
+Fetch a particular users details, matching the provided user info, from the realm
+specified in $realm.
+
+=back
=head1 INTERNAL METHODS
-=over 4
+These methods are for Catalyst::Plugin::Authentication B<INTERNAL USE> only.
+Please do not use them in your own code, whether application or credential /
+store modules. If you do, you will very likely get the nasty shock of having
+to fix / rewrite your code when things change. They are documented here only
+for reference.
-=item set_authenticated $user
+=over 4
-Marks a user as authenticated. Should be called from a
-C<Catalyst::Plugin::Authentication::Credential> plugin after successful
-authentication.
+=item set_authenticated ( $user, $realmname )
-This involves setting C<user> and the internal data in C<session> if
-L<Catalyst::Plugin::Session> is loaded.
+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
+=item auth_restore_user ( $user, $realmname )
-Used to restore a user from the session, by C<user> only when it's actually
-needed.
+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
+=item save_user_in_session ( $user, $realmname )
-Used to save the user in a session.
+Used to save the user in a session. Saves $user in session, marked as
+originating in $realmname. Both arguments are required.
-=item prepare
+=item auth_realms
-Revives a user from the session object if there is one.
+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 setup
+=item get_auth_realm ( $realmname )
-Sets the default configuration parameters.
+Retrieves the realm instance for the realmname provided.
=item
=head1 SEE ALSO
-This list might not be up to date.
+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 User Storage Backends
L<Catalyst::Plugin::Authentication::Store::Minimal>,
-L<Catalyst::Plugin::Authentication::Store::Htpasswd>,
-L<Catalyst::Plugin::Authentication::Store::DBIC> (also works with Class::DBI).
+L<Catalyst::Plugin::Authentication::Store::DBIx::Class>,
=head2 Credential verification
L<Catalyst::Plugin::Authentication::Credential::Password>,
-L<Catalyst::Plugin::Authentication::Credential::HTTP>,
-L<Catalyst::Plugin::Authentication::Credential::TypeKey>
=head2 Authorization
=head2 Internals Documentation
-L<Catalyst::Plugin::Authentication::Store>
+L<Catalyst::Plugin::Authentication::Internals>
=head2 Misc
L<Catalyst::Plugin::Authentication::CDBI::Basic>,
L<Catalyst::Plugin::Authentication::Basic::Remote>.
+=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 can
+not 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 ROUTINES
-=over 4
+In version 0.10 of L<Catalyst::Plugin::Authentication>, the API
+changed. For app developers, this change is fairly minor, but for
+Credential and Store authors, the changes are significant.
-In version 0.10 of the L<Catalyst::Plugin::Authentication> plugin, the API
-used changed. For app developers, this change is fairly minor, but for
-Credential and Store authors, the changes are significant. The items below are
-still present in the plugin, though using them is deprecated. They remain only
-as a transition tool, for those sites which can not be upgraded to use the new
-system due to local customizations, or use of Credential / store modules that
-have not yet been updated.
-
-=head1 METHODS FOR STORE MANAGEMENT
+Please see the documentation in version 0.09 of
+Catalyst::Plugin::Authentication for a better understanding of how the old API
+functioned.
+
+The items below are still present in the plugin, though using them is
+deprecated. They remain only as a transition tool, for those sites which can
+not yet be upgraded to use the new system due to local customizations or use
+of Credential / Store modules that have not yet been updated to work with the
+new API.
+
+These routines should not be used in any application using realms
+functionality or any of the methods described above. These are for reference
+purposes only.
=over 4
+=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
Return the store whose name is 'default'.
This is set to C<< $c->config->{authentication}{store} >> if that value exists,
or by using a Store plugin:
+ # load the Minimal authentication store.
use Catalyst qw/Authentication Authentication::Store::Minimal/;
Sets the default store to
-L<Catalyst::Plugin::Authentication::Store::Minimal::Backend>.
-
+L<Catalyst::Plugin::Authentication::Store::Minimal>.
=item get_auth_store $name
A hash keyed by name, with the stores registered in the app.
-=item auth_store_names
-
-A ref-hash keyed by store, which contains the names of the stores.
-
=item register_auth_stores %stores_by_name
Register stores into the application.
Yuval Kogman, C<nothingmuch@woobling.org>
+Jay Kuri, C<jayk@cpan.org>
+
Jess Robinson
David Kamholz
+
=head1 COPYRIGHT & LICENSE
Copyright (c) 2005 the aforementioned authors. All rights
projects / catagits/Catalyst-Plugin-Authentication.git / blobdiff