lib/Catalyst/Authentication/Store.pod

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