view release on metacpan or  search on metacpan

lib/Catalyst/Plugin/Authentication.pm  view on Meta::CPAN

                    admins => {
                        credential => {
                            class => 'Password',
                            password_field => 'password',
                            password_type => 'clear'
                        },
                        store => {
                            class => '+MyApp::Authentication::Store::NetAuth',
                            authserver => '192.168.10.17'
                        }
                    }
                }
    );

NOTE: Until version 0.10008 of this module, you would need to put all the
realms inside a "realms" key in the configuration. Please see
L</COMPATIBILITY CONFIGURATION> for more information

=over 4

=item use_session

Whether or not to store the user's logged in state in the session, if the
application is also using L<Catalyst::Plugin::Session>. This
value is set to true per default.

However, even if use_session is disabled, if any code touches $c->session, a session
object will be auto-vivified and session Cookies will be sent in the headers. To
prevent accidental session creation, check if a session already exists with
if ($c->sessionid) { ... }. If the session doesn't exist, then don't place
anything in the session to prevent an unecessary session from being created.

=item default_realm

This defines which realm should be used as when no realm is provided to methods
that require a realm such as authenticate or find_user.

=item realm refs

The Plugin::Authentication config hash contains the series of realm
configurations you want to use for your app. 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 may also put your
realm configurations within a subelement called 'realms' if you desire to
separate them from the remainder of your configuration.  Note that if you use
a 'realms' subelement, you must put ALL of your realms within it.

You can also specify a realm class to instantiate instead of the default
L<Catalyst::Authentication::Realm> class using the 'class' element within the
realm config.

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 ])

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.

=head2 $c->user( )

Returns the currently logged in user, or undef if there is none.
Normally the user is re-retrieved from the store.
For L<Catalyst::Authentication::Store::DBIx::Class> the user is re-restored
using the primary key of the user table.
Thus B<user> can throw an error even though B<user_exists>
returned true.

=head2 $c->user_exists( )

Returns true if a user is logged in right now. The difference between
B<user_exists> and B<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.
B<user_exists> only looks into the session while B<user> is trying to restore the user.

=head2 $c->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.

=head2 $c->logout( )

Logs the user out. Deletes the currently logged in user from C<< $c->user >>
and the session.  It does not delete the session.

=head2 $c->find_user( $userinfo, $realm )

Fetch a particular users details, matching the provided user info, from the realm
specified in $realm.

    $user = $c->find_user({ id => $id });
    $c->set_authenticated($user); # logs the user in and calls persist_user

=head2 persist_user()

Under normal circumstances the user data is only saved to the session during
initial authentication.  This call causes the auth system to save the
currently authenticated user's data across requests.  Useful if you have
changed the user data and want to ensure that future requests reflect the
most current data.  Assumes that at the time of this call, $c->user
contains the most current data.

=head2 find_realm_for_persisted_user()

lib/Catalyst/Plugin/Authentication.pm  view on Meta::CPAN

=item L<Catalyst::Authentication::Store::DBIx::Class>

=item L<Catalyst::Authentication::Store::LDAP>

=item L<Catalyst::Authentication::Store::RDBO>

=item L<Catalyst::Authentication::Store::Model::KiokuDB>

=item L<Catalyst::Authentication::Store::Jifty::DBI>

=item L<Catalyst::Authentication::Store::Htpasswd>

=back

=head2 Credential verification

=over

=item L<Catalyst::Authentication::Credential::Password>

=item L<Catalyst::Authentication::Credential::HTTP>

=item L<Catalyst::Authentication::Credential::OpenID>

=item L<Catalyst::Authentication::Credential::Authen::Simple>

=item L<Catalyst::Authentication::Credential::Flickr>

=item L<Catalyst::Authentication::Credential::Testing>

=item L<Catalyst::Authentication::Credential::AuthTkt>

=item L<Catalyst::Authentication::Credential::Kerberos>

=back

=head2 Authorization

L<Catalyst::Plugin::Authorization::ACL>,
L<Catalyst::Plugin::Authorization::Roles>

=head2 Internals Documentation

L<Catalyst::Plugin::Authentication::Internals>

=head2 Misc

L<Catalyst::Plugin::Session>,
L<Catalyst::Plugin::Session::PerUser>

=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
realms inside a "realms" key in the configuration.

    # example
    __PACKAGE__->config( 'Plugin::Authentication' =>
                {
                    default_realm => 'members',
                    realms => {
                        members => {
                            ...
                        },
                    },
                }
    );

If you use the old, deprecated C<< __PACKAGE__->config( 'authentication' ) >>
configuration key, then the realms key is still required.

=head1 COMPATIBILITY ROUTINES

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.

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.

=head2 $c->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.

=head2 $c->default_auth_store( )

Return the store whose name is 'default'.

This is set to C<< $c->config( 'Plugin::Authentication' => { store => # Store} ) >> if that value exists,
or by using a Store plugin: