1Catalyst::AuthenticatioUns:e:rStCoornet(r3i)buted Perl DCoactuamleynstta:t:iAounthentication::Store(3)
2
3
4

NAME

6       Catalyst::Authentication::Store - All about authentication stores
7

MULTIPLE BACKENDS

9       NOTE This is documentation for the old store system used in versions of
10       Catalyst::Plugin::Authentication prior to 0.10.  This is NOT how the
11       new realm-based stores work. This is here for reference only.
12
13       See Catalyst::Plugin::Authentication::Internals instead.
14

OLD STORE DOCUMENTATION BELOW

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,
18       and has a name.
19
20       For most applications, there is only one, and in this framework it is
21       called '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
31       than check out the configuration, and register e.g. Store::Foo, and set
32       it 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

WORKING WITH USERS

41       All credential verifiers should accept either a user object, or a user
42       ID.
43
44       If a user ID is provided, then they will fetch the user object from the
45       default 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
50       must 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

WRITING A BACKEND

63       Writing an authentication storage backend is a very simple matter.
64
65       The only method you really need to support is "get_user".
66
67       This method should accept an arbitrary list of parameters (determined
68       by you or the credential verifyer), and return an object inheriting
69       Catalyst::Authentication::User.
70
71       For introspection purposes you can also define the "user_supports"
72       method. See below for optional features. This is not necessary, but
73       might be in the future.
74
75   Integrating with Catalyst::Plugin::Session
76       If your users support sessions, your store should also define the
77       "from_session" method. When the user object is saved in the session the
78       "for_session" method is called, and that is used as the value in the
79       session (typically a user id). The store is also saved in the hash. If
80       "$user->store" returns something registered, that store's name is used.
81       If not, the user's class is used as if it were a store (and must also
82       support "from_session").
83
84   Optional Features
85       Each user has the "supports" method. For example:
86
87           $user->supports(qw/password clear/);
88
89       should return a true value if this specific user has a clear text
90       password.
91
92       This is on a per user (not necessarily a per store) basis. To make
93       assumptions about the store as a whole,
94
95           $store->user_supports(qw/password clear/);
96
97       is supposed to be the lowest common denominator.
98
99       The standardization of these values is to be goverened by the
100       community, typically defined by the credential verification plugins.
101
102   Stores implying certain credentials
103       Sometimes a store is agnostic to the credentials (DB storage, for
104       example), but sometimes it isn't (like an Htpasswd file).
105
106       If you are writing a backend that wraps around a module, like
107       Catalyst::Authentication::Store::Htpasswd wraps around
108       Authen::Htpasswd, it makes sense to delegate the credential checks.
109
110       This particular example caused the following "feature" to be added:
111
112           $user->supports(qw/password self_check/);
113
114   Writing a plugin to go with the backend
115       Typically the backend will do the heavy lifting, by registering a
116       store.
117
118       These plugins should look something like this:
119
120           sub setup {
121               my $c = shift;
122
123               $c->default_auth_store(
124                   # a store can be an object or a class
125                   Catalyst::Authentication::Store::Foo::Backend->new(
126                       ...
127                   )
128               );
129
130               $c->NEXT::setup(@_);
131           }
132
133
134
135perl v5.38.0                      2023-07-20Catalyst::Authentication::Store(3)