Commit | Line | Data |
6876341d |
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 | |
69271f57 |
42 | Instead of just: |
43 | |
44 | $c->login( $id, $supplied_password ); |
45 | |
46 | which will go to the default store. |
47 | |
6876341d |
48 | =head1 WRITING A BACKEND |
49 | |
50 | Writing an authentication storage backend is a very simple matter. |
51 | |
52 | The only method you really need to support is C<get_user>. |
53 | |
54 | This method should accept an arbitrary list of parameters (determined by you or |
55 | the credential verifyer), and return an object inheriting |
56 | L<Catalyst::Plugin::Authentication::User>. |
57 | |
58 | For introspection purposes you can also define the C<user_supports> method. See |
59 | below for optional features. This is not necessary, but might be in the future. |
60 | |
61 | =head2 Integrating with Catalyst::Plugin::Session |
62 | |
63 | If your users support sessions, your store should also define the |
64 | C<from_session> method. When the user object is saved in the session the |
65 | C<for_session> method is called, and that is used as the value in the session |
66 | (typically a user id). The store is also saved in the hash. If |
67 | C<<$user->store>> returns something registered, that store's name is used. If |
68 | not, the user's class is used as if it were a store (and must also support |
69 | C<from_session>). |
70 | |
71 | =head2 Optional Features |
72 | |
73 | Each user has the C<supports> method. For example: |
74 | |
75 | $user->supports(qw/password clear/); |
76 | |
77 | should return a true value if this specific user has a clear text password. |
78 | |
79 | This is on a per user (not necessarily a per store) basis. To make assumptions |
80 | about the store as a whole, |
81 | |
82 | $store->user_supports(qw/password clear/); |
83 | |
84 | is supposed to be the lowest common denominator. |
85 | |
86 | The standardization of these values is to be goverened by the community, |
87 | typically defined by the credential verification plugins. |
88 | |
89 | =head2 Stores implying certain credentials |
90 | |
91 | Sometimes a store is agnostic to the credentials (DB storage, for example), but |
92 | sometimes it isn't (like an Htpasswd file). |
93 | |
94 | If you are writing a backend that wraps around a module, like |
95 | L<Catalyst::Plugin::Authentication::Store::Htpasswd> wraps around |
96 | L<Authen::Htpasswd>, it makes sense to delegate the credential checks. |
97 | |
98 | This particular example caused the following "feature" to be added: |
99 | |
100 | $user->supports(qw/password self_check/); |
101 | |
102 | =head2 Writing a plugin to go with the backend |
103 | |
104 | Typically the backend will do the heavy lifting, by registering a store. |
105 | |
106 | These plugins should look something like this: |
107 | |
108 | sub setup { |
109 | my $c = shift; |
110 | |
111 | $c->default_auth_store( |
112 | # a store can be an object or a class |
113 | Catalyst::Plugin::Authentication::Store::Foo::Backend->new( |
114 | ... |
115 | ) |
116 | ); |
117 | |
118 | $c->NEXT::setup(@_); |
119 | } |