1Catalyst::AuthenticatioUns:e:rCrCeodnetnrtiibCaualtt:ea:dlHyTPsTetPr:(l:3A)Duotchuemnetnitcaattiioonn::Credential::HTTP(3)
2
6 Catalyst::Authentication::Credential::HTTP - HTTP Basic and Digest
7 authentication for Catalyst
8
10 version 1.018
11
13 use Catalyst qw/
14 Authentication
15 /;
16 __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 sub foo : Local {
38 my ( $self, $c ) = @_;
39 $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 do_stuff();
49 }
50 sub always_auth : Local {
52 my ( $self, $c ) = @_;
53 # 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 # with ACL plugin
62 __PACKAGE__->deny_access_unless("/path", sub { $_[0]->authenticate });
63
65 This module lets you use HTTP authentication with
66 Catalyst::Plugin::Authentication. Both basic and digest authentication
67 are currently supported.
68 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 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
84 new $config, $c, $realm
85 Simple constructor.
86 init
88 Validates that $config is ok.
89 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 Looks inside "$c->request->headers" and processes the digest and
96 basic (badly named) authorization header.
97 This will only try the methods set in the configuration. First
99 digest, then basic.
100 The %auth_info hash can contain a number of keys which control the
102 authentication behaviour:
103 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 domain
110 Array reference to domains used to build the authorization
111 headers.
112 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 The client will use this list to determine the set of URIs for
120 which the same authentication information may be sent.
121 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 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 authenticate_basic $c, $realm, \%auth_info
133 Performs HTTP basic authentication.
134 authenticate_digest $c, $realm, \%auth_info
136 Performs HTTP digest authentication.
137 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 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 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 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 Typically used by "authenticate", but may be invoked manually.
157 %opts can contain "domain" and "algorithm", which are used to build
159 %the digest header.
160 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 You may override these methods. By default they will call "get" and
166 "set" on "$c->cache".
167 authentication_failed
169 Sets the 401 response and calls "$ctx->detach".
170
172 All configuration is stored in
173 "YourApp->config('Plugin::Authentication' => { yourrealm => {
174 credential => { class => 'HTTP', %config } } }".
175 This should be a hash, and it can contain the following entries:
177 type
179 Can be either "any" (the default), "basic" or "digest".
180 This controls "authorization_required_response" and "authenticate",
182 but not the "manual" methods.
183 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 password_type
190 The type of password returned by the user object. Same usage as in
191 Catalyst::Authentication::Credential::Password
192 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 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 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 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 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 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 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 This option has no effect on clients that include the query string;
233 they will continue to work as normal.
234
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
244 RFC 2617 (or its successors), Catalyst::Plugin::Cache,
245 Catalyst::Plugin::Authentication
246
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 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 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
261 יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
262
264 · Tomas Doran <bobtfish@bobtfish.net>
265 · Karen Etheridge <ether@cpan.org>
267 · Sascha Kiefer <esskar@cpan.org>
269 · Devin Austin <devin.austin@gmail.com>
271 · Ronald J Kimball <rjk@linguist.dartmouth.edu>
273 · Jess Robinson <cpan@desert-island.me.uk>
275 · Ronald J Kimball <rjk@tamias.net>
277 · Tomas Doran <tdoran@yelp.com>
279 · Ton Voon <ton.voon@opsera.com>
281 · J. Shirley <jshirley+cpan@gmail.com>
283 · Brian Cassidy <bricas@cpan.org>
285 · Jonathan Rockway <jon@jrock.us>
287
289 This software is copyright (c) 2006 by יובל קוג'מן (Yuval Kogman).
290 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.
293perl v5.28.0 C2a0t1a7l-y0s6t-:2:8Authentication::Credential::HTTP(3)