lib/Catalyst/Plugin/Authentication/Store.pod

   1
   2 =head1 NAME
   3
   4 Catalyst::Plugin::Authentication::Store - All about authentication stores
   5
   6 =head1 MULTIPLE BACKENDS
   7
   8 A key issue to understand about authentication stores is that there are
   9 potentially many of them. Each one is registered into the application, and has
  10 a name.
  11
  12 For most applications, there is only one, and in this framework it is called
  13 'default'.
  14
  15 When you use a plugin, like
  16
  17     use Catalyst qw/
  18         Authentication
  19         Authentication::Store::Foo
  20     /;
  21
  22 the Store plugins typically only act at setup time. They rarely do more than
  23 check out the configuration, and register e.g. Store::Foo::Backend, and set it
  24 as the default store.
  25
  26 =head1 WORKING WITH USERS
  27
  28 All credential verifiers should accept either a user object, or a user ID.
  29
  30 If a user ID is provided, then they will fetch the user object from the default
  31 store, and check against it.
  32
  33 This should be pretty much DWIM all the time.
  34
  35 When you need multiple authentication backends per application then you must
  36 fetch things yourself. For example:
  37
  38     my $user = $c->get_auth_store("other_store")->get_user($id);
  39
  40     $c->login( $user, $supplied_password );
  41
  42 =head1 WRITING A BACKEND
  43
  44 Writing an authentication storage backend is a very simple matter.
  45
  46 The only method you really need to support is C<get_user>.
  47
  48 This method should accept an arbitrary list of parameters (determined by you or
  49 the credential verifyer), and return an object inheriting
  50 L<Catalyst::Plugin::Authentication::User>.
  51
  52 For introspection purposes you can also define the C<user_supports> method. See
  53 below for optional features. This is not necessary, but might be in the future.
  54
  55 =head2 Integrating with Catalyst::Plugin::Session
  56
  57 If your users support sessions, your store should also define the
  58 C<from_session> method. When the user object is saved in the session the
  59 C<for_session> method is called, and that is used as the value in the session
  60 (typically a user id). The store is also saved in the hash. If
  61 C<<$user->store>> returns something registered, that store's name is used. If
  62 not, the user's class is used as if it were a store (and must also support
  63 C<from_session>).
  64
  65 =head2 Optional Features
  66
  67 Each user has the C<supports> method. For example:
  68
  69     $user->supports(qw/password clear/);
  70
  71 should return a true value if this specific user has a clear text password.
  72
  73 This is on a per user (not necessarily a per store) basis. To make assumptions
  74 about the store as a whole,
  75
  76     $store->user_supports(qw/password clear/);
  77
  78 is supposed to be the lowest common denominator.
  79
  80 The standardization of these values is to be goverened by the community,
  81 typically defined by the credential verification plugins.
  82
  83 =head2 Stores implying certain credentials
  84
  85 Sometimes a store is agnostic to the credentials (DB storage, for example), but
  86 sometimes it isn't (like an Htpasswd file).
  87
  88 If you are writing a backend that wraps around a module, like
  89 L<Catalyst::Plugin::Authentication::Store::Htpasswd> wraps around
  90 L<Authen::Htpasswd>, it makes sense to delegate the credential checks.
  91
  92 This particular example caused the following "feature" to be added:
  93
  94     $user->supports(qw/password self_check/);
  95
  96 =head2 Writing a plugin to go with the backend
  97
  98 Typically the backend will do the heavy lifting, by registering a store.
  99
 100 These plugins should look something like this:
 101
 102     sub setup {
 103         my $c = shift;
 104
 105         $c->default_auth_store(
 106             # a store can be an object or a class
 107             Catalyst::Plugin::Authentication::Store::Foo::Backend->new(
 108                 ...
 109             )
 110         );
 111
 112         $c->NEXT::setup(@_);
 113     }