Commit | Line | Data |
6876341d |
1 | |
2 | =head1 NAME |
3 | |
5c5af345 |
4 | Catalyst::Authentication::Store - All about authentication stores |
6876341d |
5 | |
6 | =head1 MULTIPLE BACKENDS |
7 | |
c5fbff80 |
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 | |
5c5af345 |
12 | See L<Catalyst::Authentication::Internals> instead. |
45c7644b |
13 | |
c5fbff80 |
14 | =head1 OLD STORE DOCUMENTATION BELOW |
15 | |
6876341d |
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 |
45c7644b |
31 | check out the configuration, and register e.g. Store::Foo, and set it |
6876341d |
32 | as the default store. |
33 | |
59f1e010 |
34 | __PACKAGE__->default_auth_store( $store ); |
35 | |
36 | # the same as |
37 | |
38 | __PACKAGE__->register_auth_stores( default => $store ); |
39 | |
6876341d |
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 | |
69271f57 |
56 | Instead of just: |
57 | |
58 | $c->login( $id, $supplied_password ); |
59 | |
60 | which will go to the default store. |
61 | |
6876341d |
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 |
5c5af345 |
70 | L<Catalyst::Authentication::User>. |
6876341d |
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 |
5c5af345 |
109 | L<Catalyst::Authentication::Store::Htpasswd> wraps around |
6876341d |
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 |
5c5af345 |
127 | Catalyst::Authentication::Store::Foo::Backend->new( |
6876341d |
128 | ... |
129 | ) |
130 | ); |
131 | |
132 | $c->NEXT::setup(@_); |
133 | } |