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