7 Catalyst::Authentication::Credential::HTTP - HTTP Basic and Digest authentication for Catalyst
19 __PACKAGE__->config( authentication => {
20 default_realm => 'example',
25 type => 'any', # or 'digest' or 'basic'
26 password_type => 'clear',
27 password_field => 'password'
32 Mufasa => { password => "Circle Of Life", },
40 my ( $self, $c ) = @_;
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')
53 sub always_auth : Local {
54 my ( $self, $c ) = @_;
56 # Force authorization headers onto the response so that the user
57 # is asked again for authentication, even if they successfully
59 my $realm = $c->get_auth_realm('example');
60 $realm->credential->authorization_required_response($c, $realm);
64 __PACKAGE__->deny_access_unless("/path", sub { $_[0]->authenticate });
68 This module lets you use HTTP authentication with
69 L<Catalyst::Plugin::Authentication>. Both basic and digest authentication
70 are currently supported.
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.
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.
101 =item new $config, $c, $realm
107 Validates that $config is ok.
109 =item authenticate $c, $realm, \%auth_info
111 Tries to authenticate the user, and if that fails calls
112 C<authorization_required_response> and detaches the current action call stack.
114 Looks inside C<< $c->request->headers >> and processes the digest and basic
115 (badly named) authorization header.
117 This will only try the methods set in the configuration. First digest, then basic.
119 The %auth_info hash can contain a number of keys which control the authentication behaviour:
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.
130 Array reference to domains used to build the authorization headers.
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.
136 The client will use this list to determine the set of URIs for which the same authentication
137 information may be sent.
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.
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</>.
148 =item authenticate_basic $c, $realm, \%auth_info
150 Performs HTTP basic authentication.
152 =item authenticate_digest $c, $realm, \%auth_info
154 Performs HTTP digest authentication.
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'.
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.
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.
169 =item authorization_required_response $c, $realm, \%auth_info
171 Sets C<< $c->response >> to the correct status code, and adds the correct
172 header to demand authentication data from the user agent.
174 Typically used by C<authenticate>, but may be invoked manually.
176 %opts can contain C<domain> and C<algorithm>, which are used to build
179 =item store_digest_authorization_nonce $c, $key, $nonce
181 =item get_digest_authorization_nonce $c, $key
183 Set or get the C<$nonce> object used by the digest auth mode.
185 You may override these methods. By default they will call C<get> and C<set> on
188 =item authentication_failed
190 Sets the 401 response and calls C<< $ctx->detach >>.
196 All configuration is stored in C<< YourApp->config('Plugin::Authentication' => { yourrealm => { credential => { class => 'HTTP', %config } } } >>.
198 This should be a hash, and it can contain the following entries:
204 Can be either C<any> (the default), C<basic> or C<digest>.
206 This controls C<authorization_required_response> and C<authenticate>, but
207 not the "manual" methods.
209 =item authorization_required_message
211 Set this to a string to override the default body content "Authorization required.", or set to undef to suppress body content being generated.
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>
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>
225 The field name that the user's username is mapped into when finding the user from the realm. Defaults to 'username'.
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.
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.
239 =item no_unprompted_authorization_required
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.
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.
251 =item broken_dotnet_digest_without_query_string
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.
257 This option has no effect on clients that include the query string;
258 they will continue to work as normal.
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.
273 RFC 2617 (or its successors), L<Catalyst::Plugin::Cache>, L<Catalyst::Plugin::Authentication>
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>).
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>.
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>.
288 יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
292 =for stopwords Tomas Doran Karen Etheridge Sascha Kiefer Devin Austin Ronald J Kimball Jess Robinson Ton Voon J. Shirley Brian Cassidy Jonathan Rockway
298 Tomas Doran <bobtfish@bobtfish.net>
302 Karen Etheridge <ether@cpan.org>
306 Sascha Kiefer <esskar@cpan.org>
310 Devin Austin <devin.austin@gmail.com>
314 Ronald J Kimball <rjk@linguist.dartmouth.edu>
318 Jess Robinson <cpan@desert-island.me.uk>
322 Ronald J Kimball <rjk@tamias.net>
326 Tomas Doran <tdoran@yelp.com>
330 Ton Voon <ton.voon@opsera.com>
334 J. Shirley <jshirley+cpan@gmail.com>
338 Brian Cassidy <bricas@cpan.org>
342 Jonathan Rockway <jon@jrock.us>
346 =head1 COPYRIGHT AND LICENCE
348 This software is copyright (c) 2006 by יובל קוג'מן (Yuval Kogman).
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.