1Catalyst::AuthenticatioUns:e:rCrCeodnetnrtiibCaualtt:ea:dlHyTPsTetPr:(l:3A)Duotchuemnetnitcaattiioonn::Credential::HTTP(3)
2
3
4

NAME

6       Catalyst::Authentication::Credential::HTTP - HTTP Basic and Digest
7       authentication for Catalyst
8

VERSION

10       version 1.018
11

SYNOPSIS

13           use Catalyst qw/
14               Authentication
15           /;
16
17           __PACKAGE__->config( authentication => {
18               default_realm => 'example',
19               realms => {
20                   example => {
21                       credential => {
22                           class => 'HTTP',
23                           type  => 'any', # or 'digest' or 'basic'
24                           password_type  => 'clear',
25                           password_field => 'password'
26                       },
27                       store => {
28                           class => 'Minimal',
29                           users => {
30                               Mufasa => { password => "Circle Of Life", },
31                           },
32                       },
33                   },
34               }
35           });
36
37           sub foo : Local {
38               my ( $self, $c ) = @_;
39
40               $c->authenticate({}, "example");
41               # either user gets authenticated or 401 is sent
42               # Note that the authentication realm sent to the client (in the
43               # RFC 2617 sense) is overridden here, but this *does not*
44               # effect the Catalyst::Authentication::Realm used for
45               # authentication - to do that, you need
46               # $c->authenticate({}, 'otherrealm')
47
48               do_stuff();
49           }
50
51           sub always_auth : Local {
52               my ( $self, $c ) = @_;
53
54               # Force authorization headers onto the response so that the user
55               # is asked again for authentication, even if they successfully
56               # authenticated.
57               my $realm = $c->get_auth_realm('example');
58               $realm->credential->authorization_required_response($c, $realm);
59           }
60
61           # with ACL plugin
62           __PACKAGE__->deny_access_unless("/path", sub { $_[0]->authenticate });
63

DESCRIPTION

65       This module lets you use HTTP authentication with
66       Catalyst::Plugin::Authentication. Both basic and digest authentication
67       are currently supported.
68
69       When authentication is required, this module sets a status of 401, and
70       the body of the response to 'Authorization required.'. To override this
71       and set your own content, check for the "$c->res->status == 401" in
72       your "end" action, and change the body accordingly.
73
74   TERMS
75       Nonce
76           A nonce is a one-time value sent with each digest authentication
77           request header. The value must always be unique, so per default the
78           last value of the nonce is kept using Catalyst::Plugin::Cache. To
79           change this behaviour, override the
80           "store_digest_authorization_nonce" and
81           "get_digest_authorization_nonce" methods as shown below.
82

METHODS

84       new $config, $c, $realm
85           Simple constructor.
86
87       init
88           Validates that $config is ok.
89
90       authenticate $c, $realm, \%auth_info
91           Tries to authenticate the user, and if that fails calls
92           "authorization_required_response" and detaches the current action
93           call stack.
94
95           Looks inside "$c->request->headers" and processes the digest and
96           basic (badly named) authorization header.
97
98           This will only try the methods set in the configuration. First
99           digest, then basic.
100
101           The %auth_info hash can contain a number of keys which control the
102           authentication behaviour:
103
104           realm
105               Sets the HTTP authentication realm presented to the client.
106               Note this does not alter the Catalyst::Authentication::Realm
107               object used for the authentication.
108
109           domain
110               Array reference to domains used to build the authorization
111               headers.
112
113               This list of domains defines the protection space. If a domain
114               URI is an absolute path (starts with /), it is relative to the
115               root URL of the server being accessed.  An absolute URI in this
116               list may refer to a different server than the one being
117               accessed.
118
119               The client will use this list to determine the set of URIs for
120               which the same authentication information may be sent.
121
122               If this is omitted or its value is empty, the client will
123               assume that the protection space consists of all URIs on the
124               responding server.
125
126               Therefore, if your application is not hosted at the root of
127               this domain, and you want to prevent the authentication
128               credentials for this application being sent to any other
129               applications.  then you should use the use_uri_for
130               configuration option, and pass a domain of /.
131
132       authenticate_basic $c, $realm, \%auth_info
133           Performs HTTP basic authentication.
134
135       authenticate_digest $c, $realm, \%auth_info
136           Performs HTTP digest authentication.
137
138           The password_type must be clear for digest authentication to
139           succeed.  If you do not want to store your user passwords as clear
140           text, you may instead store the MD5 digest in hex of the string
141           '$username:$realm:$password'.
142
143           Catalyst::Plugin::Cache is used for persistent storage of the nonce
144           values (see "Nonce").  It must be loaded in your application,
145           unless you override the "store_digest_authorization_nonce" and
146           "get_digest_authorization_nonce" methods as shown below.
147
148           Takes an additional parameter of algorithm, the possible values of
149           which are 'MD5' (the default) and 'MD5-sess'. For more information
150           about 'MD5-sess', see section 3.2.2.2 in RFC 2617.
151
152       authorization_required_response $c, $realm, \%auth_info
153           Sets "$c->response" to the correct status code, and adds the
154           correct header to demand authentication data from the user agent.
155
156           Typically used by "authenticate", but may be invoked manually.
157
158           %opts can contain "domain" and "algorithm", which are used to build
159           %the digest header.
160
161       store_digest_authorization_nonce $c, $key, $nonce
162       get_digest_authorization_nonce $c, $key
163           Set or get the $nonce object used by the digest auth mode.
164
165           You may override these methods. By default they will call "get" and
166           "set" on "$c->cache".
167
168       authentication_failed
169           Sets the 401 response and calls "$ctx->detach".
170

CONFIGURATION

172       All configuration is stored in
173       "YourApp->config('Plugin::Authentication' => { yourrealm => {
174       credential => { class => 'HTTP', %config } } }".
175
176       This should be a hash, and it can contain the following entries:
177
178       type
179           Can be either "any" (the default), "basic" or "digest".
180
181           This controls "authorization_required_response" and "authenticate",
182           but not the "manual" methods.
183
184       authorization_required_message
185           Set this to a string to override the default body content
186           "Authorization required.", or set to undef to suppress body content
187           being generated.
188
189       password_type
190           The type of password returned by the user object. Same usage as in
191           Catalyst::Authentication::Credential::Password
192
193       password_field
194           The name of accessor used to retrieve the value of the password
195           field from the user object. Same usage as in
196           Catalyst::Authentication::Credential::Password
197
198       username_field
199           The field name that the user's username is mapped into when finding
200           the user from the realm. Defaults to 'username'.
201
202       use_uri_for
203           If this configuration key has a true value, then the domain(s) for
204           the authorization header will be run through $c->uri_for(). Use
205           this configuration option if your application is not running at the
206           root of your domain, and you want to ensure that authentication
207           credentials from your application are not shared with other
208           applications on the same server.
209
210       require_ssl
211           If this configuration key has a true value then authentication will
212           be denied (and a 401 issued in normal circumstances) unless the
213           request is via https.
214
215       no_unprompted_authorization_required
216           Causes authentication to fail as normal modules do, without calling
217           "$c->detach". This means that the basic auth credential can be used
218           as part of the progressive realm.
219
220           However use like this is probably not optimum it also means that
221           users in browsers ill never get a HTTP authenticate dialogue box
222           (unless you manually return a 401 response in your application),
223           and even some automated user agents (for APIs) will not send the
224           Authorization header without specific manipulation of the request
225           headers.
226
227       broken_dotnet_digest_without_query_string
228           Enables support for .NET (or other similarly broken clients), which
229           fails to include the query string in the uri in the digest
230           Authorization header, contrary to rfc2617.
231
232           This option has no effect on clients that include the query string;
233           they will continue to work as normal.
234

RESTRICTIONS

236       When using digest authentication, this module will only work together
237       with authentication stores whose User objects have a "password" method
238       that returns the plain-text password. It will not work together with
239       Catalyst::Authentication::Store::Htpasswd, or
240       Catalyst::Authentication::Store::DBIC stores whose "password" methods
241       return a hashed or salted version of the password.
242

SEE ALSO

244       RFC 2617 (or its successors), Catalyst::Plugin::Cache,
245       Catalyst::Plugin::Authentication
246

SUPPORT

248       Bugs may be submitted through the RT bug tracker
249       <https://rt.cpan.org/Public/Dist/Display.html?Name=Catalyst-
250       Authentication-Credential-HTTP> (or
251       bug-Catalyst-Authentication-Credential-HTTP@rt.cpan.org <mailto:bug-
252       Catalyst-Authentication-Credential-HTTP@rt.cpan.org>).
253
254       There is also a mailing list available for users of this distribution,
255       at <http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst>.
256
257       There is also an irc channel available for users of this distribution,
258       at "#catalyst" on "irc.perl.org" <irc://irc.perl.org/#catalyst>.
259

AUTHOR

261       יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
262

CONTRIBUTORS

264       •   Tomas Doran <bobtfish@bobtfish.net>
265
266       •   Karen Etheridge <ether@cpan.org>
267
268       •   Sascha Kiefer <esskar@cpan.org>
269
270       •   Devin Austin <devin.austin@gmail.com>
271
272       •   Ronald J Kimball <rjk@linguist.dartmouth.edu>
273
274       •   Jess Robinson <cpan@desert-island.me.uk>
275
276       •   Ronald J Kimball <rjk@tamias.net>
277
278       •   Tomas Doran <tdoran@yelp.com>
279
280       •   Ton Voon <ton.voon@opsera.com>
281
282       •   J. Shirley <jshirley+cpan@gmail.com>
283
284       •   Brian Cassidy <bricas@cpan.org>
285
286       •   Jonathan Rockway <jon@jrock.us>
287
289       This software is copyright (c) 2006 by יובל קוג'מן (Yuval Kogman).
290
291       This is free software; you can redistribute it and/or modify it under
292       the same terms as the Perl 5 programming language system itself.
293
294
295
296perl v5.34.0                     C2a0t2a2l-y0s1t-:2:0Authentication::Credential::HTTP(3)
Impressum