README.pod

   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
  11 version 1.018
  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