Commit | Line | Data |
5010bd74 |
1 | =pod |
2 | |
3 | =encoding UTF-8 |
4 | |
5 | =head1 NAME |
6 | |
7 | Catalyst::Authentication::Credential::HTTP - HTTP Basic and Digest authentication for Catalyst |
8 | |
9 | =head1 VERSION |
10 | |
91af44aa |
11 | version 1.018 |
5010bd74 |
12 | |
13 | =head1 SYNOPSIS |
14 | |
15 | use Catalyst qw/ |
16 | Authentication |
17 | /; |
18 | |
19 | __PACKAGE__->config( authentication => { |
20 | default_realm => 'example', |
21 | realms => { |
22 | example => { |
23 | credential => { |
24 | class => 'HTTP', |
25 | type => 'any', # or 'digest' or 'basic' |
26 | password_type => 'clear', |
27 | password_field => 'password' |
28 | }, |
29 | store => { |
30 | class => 'Minimal', |
31 | users => { |
32 | Mufasa => { password => "Circle Of Life", }, |
33 | }, |
34 | }, |
35 | }, |
36 | } |
37 | }); |
38 | |
39 | sub foo : Local { |
40 | my ( $self, $c ) = @_; |
41 | |
42 | $c->authenticate({}, "example"); |
43 | # either user gets authenticated or 401 is sent |
44 | # Note that the authentication realm sent to the client (in the |
45 | # RFC 2617 sense) is overridden here, but this *does not* |
46 | # effect the Catalyst::Authentication::Realm used for |
47 | # authentication - to do that, you need |
48 | # $c->authenticate({}, 'otherrealm') |
49 | |
50 | do_stuff(); |
51 | } |
52 | |
53 | sub always_auth : Local { |
54 | my ( $self, $c ) = @_; |
55 | |
56 | # Force authorization headers onto the response so that the user |
57 | # is asked again for authentication, even if they successfully |
58 | # authenticated. |
59 | my $realm = $c->get_auth_realm('example'); |
60 | $realm->credential->authorization_required_response($c, $realm); |
61 | } |
62 | |
63 | # with ACL plugin |
64 | __PACKAGE__->deny_access_unless("/path", sub { $_[0]->authenticate }); |
65 | |
66 | =head1 DESCRIPTION |
67 | |
68 | This module lets you use HTTP authentication with |
69 | L<Catalyst::Plugin::Authentication>. Both basic and digest authentication |
70 | are currently supported. |
71 | |
72 | When authentication is required, this module sets a status of 401, and |
73 | the body of the response to 'Authorization required.'. To override |
74 | this and set your own content, check for the C<< $c->res->status == |
75 | 401 >> in your C<end> action, and change the body accordingly. |
76 | |
77 | =head2 TERMS |
78 | |
79 | =over 4 |
80 | |
81 | =item Nonce |
82 | |
83 | A nonce is a one-time value sent with each digest authentication |
84 | request header. The value must always be unique, so per default the |
85 | last value of the nonce is kept using L<Catalyst::Plugin::Cache>. To |
86 | change this behaviour, override the |
87 | C<store_digest_authorization_nonce> and |
88 | C<get_digest_authorization_nonce> methods as shown below. |
89 | |
90 | =back |
91 | |
92 | =for stopwords rfc |
93 | rfc2617 |
94 | auth |
95 | sess |
96 | |
97 | =head1 METHODS |
98 | |
99 | =over 4 |
100 | |
101 | =item new $config, $c, $realm |
102 | |
103 | Simple constructor. |
104 | |
105 | =item init |
106 | |
107 | Validates that $config is ok. |
108 | |
109 | =item authenticate $c, $realm, \%auth_info |
110 | |
111 | Tries to authenticate the user, and if that fails calls |
112 | C<authorization_required_response> and detaches the current action call stack. |
113 | |
114 | Looks inside C<< $c->request->headers >> and processes the digest and basic |
115 | (badly named) authorization header. |
116 | |
117 | This will only try the methods set in the configuration. First digest, then basic. |
118 | |
119 | The %auth_info hash can contain a number of keys which control the authentication behaviour: |
120 | |
121 | =over |
122 | |
123 | =item realm |
124 | |
125 | Sets the HTTP authentication realm presented to the client. Note this does not alter the |
126 | Catalyst::Authentication::Realm object used for the authentication. |
127 | |
128 | =item domain |
129 | |
130 | Array reference to domains used to build the authorization headers. |
131 | |
132 | This list of domains defines the protection space. If a domain URI is an |
133 | absolute path (starts with /), it is relative to the root URL of the server being accessed. |
134 | An absolute URI in this list may refer to a different server than the one being accessed. |
135 | |
136 | The client will use this list to determine the set of URIs for which the same authentication |
137 | information may be sent. |
138 | |
139 | If this is omitted or its value is empty, the client will assume that the |
140 | protection space consists of all URIs on the responding server. |
141 | |
142 | Therefore, if your application is not hosted at the root of this domain, and you want to |
143 | prevent the authentication credentials for this application being sent to any other applications. |
144 | then you should use the I<use_uri_for> configuration option, and pass a domain of I</>. |
145 | |
146 | =back |
147 | |
148 | =item authenticate_basic $c, $realm, \%auth_info |
149 | |
150 | Performs HTTP basic authentication. |
151 | |
152 | =item authenticate_digest $c, $realm, \%auth_info |
153 | |
154 | Performs HTTP digest authentication. |
155 | |
156 | The password_type B<must> be I<clear> for digest authentication to |
157 | succeed. If you do not want to store your user passwords as clear |
158 | text, you may instead store the MD5 digest in hex of the string |
159 | '$username:$realm:$password'. |
160 | |
161 | L<Catalyst::Plugin::Cache> is used for persistent storage of the nonce |
162 | values (see L</Nonce>). It must be loaded in your application, unless |
163 | you override the C<store_digest_authorization_nonce> and |
164 | C<get_digest_authorization_nonce> methods as shown below. |
165 | |
166 | Takes an additional parameter of I<algorithm>, the possible values of which are 'MD5' (the default) |
167 | and 'MD5-sess'. For more information about 'MD5-sess', see section 3.2.2.2 in RFC 2617. |
168 | |
169 | =item authorization_required_response $c, $realm, \%auth_info |
170 | |
171 | Sets C<< $c->response >> to the correct status code, and adds the correct |
172 | header to demand authentication data from the user agent. |
173 | |
174 | Typically used by C<authenticate>, but may be invoked manually. |
175 | |
176 | %opts can contain C<domain> and C<algorithm>, which are used to build |
177 | %the digest header. |
178 | |
179 | =item store_digest_authorization_nonce $c, $key, $nonce |
180 | |
181 | =item get_digest_authorization_nonce $c, $key |
182 | |
183 | Set or get the C<$nonce> object used by the digest auth mode. |
184 | |
185 | You may override these methods. By default they will call C<get> and C<set> on |
186 | C<< $c->cache >>. |
187 | |
188 | =item authentication_failed |
189 | |
190 | Sets the 401 response and calls C<< $ctx->detach >>. |
191 | |
192 | =back |
193 | |
194 | =head1 CONFIGURATION |
195 | |
196 | All configuration is stored in C<< YourApp->config('Plugin::Authentication' => { yourrealm => { credential => { class => 'HTTP', %config } } } >>. |
197 | |
198 | This should be a hash, and it can contain the following entries: |
199 | |
200 | =over |
201 | |
202 | =item type |
203 | |
204 | Can be either C<any> (the default), C<basic> or C<digest>. |
205 | |
206 | This controls C<authorization_required_response> and C<authenticate>, but |
207 | not the "manual" methods. |
208 | |
209 | =item authorization_required_message |
210 | |
211 | Set this to a string to override the default body content "Authorization required.", or set to undef to suppress body content being generated. |
212 | |
213 | =item password_type |
214 | |
215 | The type of password returned by the user object. Same usage as in |
216 | L<Catalyst::Authentication::Credential::Password|Catalyst::Authentication::Credential::Password/password_type> |
217 | |
218 | =item password_field |
219 | |
220 | The name of accessor used to retrieve the value of the password field from the user object. Same usage as in |
221 | L<Catalyst::Authentication::Credential::Password|Catalyst::Authentication::Credential::Password/password_field> |
222 | |
223 | =item username_field |
224 | |
225 | The field name that the user's username is mapped into when finding the user from the realm. Defaults to 'username'. |
226 | |
227 | =item use_uri_for |
228 | |
229 | If this configuration key has a true value, then the domain(s) for the authorization header will be |
230 | run through $c->uri_for(). Use this configuration option if your application is not running at the root |
231 | of your domain, and you want to ensure that authentication credentials from your application are not shared with |
232 | other applications on the same server. |
233 | |
234 | =item require_ssl |
235 | |
236 | If this configuration key has a true value then authentication will be denied |
237 | (and a 401 issued in normal circumstances) unless the request is via https. |
238 | |
239 | =item no_unprompted_authorization_required |
240 | |
241 | Causes authentication to fail as normal modules do, without calling |
242 | C<< $c->detach >>. This means that the basic auth credential can be used as |
243 | part of the progressive realm. |
244 | |
245 | However use like this is probably not optimum it also means that users in |
246 | browsers ill never get a HTTP authenticate dialogue box (unless you manually |
247 | return a 401 response in your application), and even some automated |
248 | user agents (for APIs) will not send the Authorization header without |
249 | specific manipulation of the request headers. |
250 | |
251 | =item broken_dotnet_digest_without_query_string |
252 | |
253 | Enables support for .NET (or other similarly broken clients), which |
254 | fails to include the query string in the uri in the digest |
255 | Authorization header, contrary to rfc2617. |
256 | |
257 | This option has no effect on clients that include the query string; |
258 | they will continue to work as normal. |
259 | |
260 | =back |
261 | |
262 | =head1 RESTRICTIONS |
263 | |
264 | When using digest authentication, this module will only work together |
265 | with authentication stores whose User objects have a C<password> |
266 | method that returns the plain-text password. It will not work together |
267 | with L<Catalyst::Authentication::Store::Htpasswd>, or |
268 | L<Catalyst::Authentication::Store::DBIC> stores whose |
269 | C<password> methods return a hashed or salted version of the password. |
270 | |
271 | =head1 SEE ALSO |
272 | |
273 | RFC 2617 (or its successors), L<Catalyst::Plugin::Cache>, L<Catalyst::Plugin::Authentication> |
274 | |
275 | =head1 SUPPORT |
276 | |
277 | Bugs may be submitted through L<the RT bug tracker|https://rt.cpan.org/Public/Dist/Display.html?Name=Catalyst-Authentication-Credential-HTTP> |
278 | (or L<bug-Catalyst-Authentication-Credential-HTTP@rt.cpan.org|mailto:bug-Catalyst-Authentication-Credential-HTTP@rt.cpan.org>). |
279 | |
280 | There is also a mailing list available for users of this distribution, at |
281 | L<http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst>. |
282 | |
283 | There is also an irc channel available for users of this distribution, at |
284 | L<C<#catalyst> on C<irc.perl.org>|irc://irc.perl.org/#catalyst>. |
285 | |
286 | =head1 AUTHOR |
287 | |
288 | יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org> |
289 | |
290 | =head1 CONTRIBUTORS |
291 | |
292 | =for stopwords Tomas Doran Karen Etheridge Sascha Kiefer Devin Austin Ronald J Kimball Jess Robinson Ton Voon J. Shirley Brian Cassidy Jonathan Rockway |
293 | |
294 | =over 4 |
295 | |
296 | =item * |
297 | |
298 | Tomas Doran <bobtfish@bobtfish.net> |
299 | |
300 | =item * |
301 | |
302 | Karen Etheridge <ether@cpan.org> |
303 | |
304 | =item * |
305 | |
306 | Sascha Kiefer <esskar@cpan.org> |
307 | |
308 | =item * |
309 | |
310 | Devin Austin <devin.austin@gmail.com> |
311 | |
312 | =item * |
313 | |
314 | Ronald J Kimball <rjk@linguist.dartmouth.edu> |
315 | |
316 | =item * |
317 | |
318 | Jess Robinson <cpan@desert-island.me.uk> |
319 | |
320 | =item * |
321 | |
322 | Ronald J Kimball <rjk@tamias.net> |
323 | |
324 | =item * |
325 | |
326 | Tomas Doran <tdoran@yelp.com> |
327 | |
328 | =item * |
329 | |
330 | Ton Voon <ton.voon@opsera.com> |
331 | |
332 | =item * |
333 | |
334 | J. Shirley <jshirley+cpan@gmail.com> |
335 | |
336 | =item * |
337 | |
338 | Brian Cassidy <bricas@cpan.org> |
339 | |
340 | =item * |
341 | |
342 | Jonathan Rockway <jon@jrock.us> |
343 | |
344 | =back |
345 | |
346 | =head1 COPYRIGHT AND LICENCE |
347 | |
348 | This software is copyright (c) 2006 by יובל קוג'מן (Yuval Kogman). |
349 | |
350 | This is free software; you can redistribute it and/or modify it under |
351 | the same terms as the Perl 5 programming language system itself. |
352 | |
353 | =cut |