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 storage backend. A pairing of a store and a credential
+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.
=head1 WRITING A STORE
-There are two parts to an authentication store, the backend and the user object.
+There are two parts to an authentication store, the store object and the user object.
=head2 STORAGE BACKEND
-Writing a storage backend is actually quite simple. There are only five methods
+Writing a store is actually quite simple. There are only five methods
that must be implemented. They are:
new() - instantiates the store object
been loaded, so your new() method must not rely on any of those being
present. If any of this is required for your store to function, you should
defer that part of initialization until the first method call.
-
+
The C<new()> method should return a blessed reference to your store object.
=item find_user( $authinfo, $c )
are below. Note that of these, only get_object is strictly required, as the
L<Catalyst::Plugin::Authentication::User|Catalyst::Plugin::Authentication::User>
base class contains reasonable implementations of the rest. If you do choose
-to implement only the C<get_object()> routine, please read the base class
-documentation so that you fully understand how the other routines will be
+to implement only the C<get_object()> routine, please read the base class code
+and documentation so that you fully understand how the other routines will be
implemented for you.
Also, your user object can implement whatever additional methods you require
=back
-... Documentation fairy fell asleep here.
-
-
-=head1 MULTIPLE BACKENDS
-
-A key issue to understand about authentication stores is that there are
-potentially many of them. Each one is registered into the application, and has
-a name.
-
-For most applications, there is only one, and in this framework it is called
-'default'.
-
-When you use a plugin, like
-
- use Catalyst qw/
- Authentication
- Authentication::Store::Foo
- /;
-
-the Store plugins typically only act at setup time. They rarely do more than
-check out the configuration, and register e.g. Store::Foo::Backend, and set it
-as the default store.
-
- __PACKAGE__->default_auth_store( $store );
-
- # the same as
-
- __PACKAGE__->register_auth_stores( default => $store );
-
-=head1 WORKING WITH USERS
-
-All credential verifiers should accept either a user object, or a user ID.
-
-If a user ID is provided, then they will fetch the user object from the default
-store, and check against it.
-
-This should be pretty much DWIM all the time.
-
-When you need multiple authentication backends per application then you must
-fetch things yourself. For example:
-
- my $user = $c->get_auth_store("other_store")->get_user($id);
-
- $c->login( $user, $supplied_password );
-
-Instead of just:
-
- $c->login( $id, $supplied_password );
-
-which will go to the default store.
-
-=head1 WRITING A BACKEND
-
-Writing an authentication storage backend is a very simple matter.
+=head1 WRITING A CREDENTIAL
-The only method you really need to support is C<get_user>.
-
-This method should accept an arbitrary list of parameters (determined by you or
-the credential verifyer), and return an object inheriting
-L<Catalyst::Plugin::Authentication::User>.
-
-For introspection purposes you can also define the C<user_supports> method. See
-below for optional features. This is not necessary, but might be in the future.
-
-=head2 Integrating with Catalyst::Plugin::Session
-
-If your users support sessions, your store should also define the
-C<from_session> method. When the user object is saved in the session the
-C<for_session> method is called, and that is used as the value in the session
-(typically a user id). The store is also saved in the hash. If
-C<<$user->store>> returns something registered, that store's name is used. If
-not, the user's class is used as if it were a store (and must also support
-C<from_session>).
-
-=head2 Optional Features
-
-Each user has the C<supports> method. For example:
-
- $user->supports(qw/password clear/);
-
-should return a true value if this specific user has a clear text password.
-
-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::Plugin::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/);
-
-=head2 Writing a plugin to go with the backend
-
-Typically the backend will do the heavy lifting, by registering a store.
-
-These plugins should look something like this:
-
- sub setup {
- my $c = shift;
-
- $c->default_auth_store(
- # a store can be an object or a class
- Catalyst::Plugin::Authentication::Store::Foo::Backend->new(
- ...
- )
- );
-
- $c->NEXT::setup(@_);
- }
+... Documentation fairy fell asleep here.
projects / catagits/Catalyst-Plugin-Authentication.git / blobdiff