README

   1 NAME
   2     Catalyst::Plugin::Authentication::Credential::HTTP - Superseded /
   3     deprecated module providing HTTP Basic and Digest authentication for
   4     Catalyst applications.
   5
   6 SYNOPSIS
   7         use Catalyst qw/
   8             Authentication
   9             Authentication::Store::Minimal
  10             Authentication::Credential::HTTP
  11         /;
  12
  13         __PACKAGE__->config->{authentication}{http}{type} = 'any'; # or 'digest' or 'basic'
  14         __PACKAGE__->config->{authentication}{users} = {
  15             Mufasa => { password => "Circle Of Life", },
  16         };
  17
  18         sub foo : Local {
  19             my ( $self, $c ) = @_;
  20
  21             $c->authorization_required( realm => "foo" ); # named after the status code ;-)
  22
  23             # either user gets authenticated or 401 is sent
  24
  25             do_stuff();
  26         }
  27
  28         # with ACL plugin
  29         __PACKAGE__->deny_access_unless("/path", sub { $_[0]->authenticate_http });
  30
  31         sub end : Private {
  32             my ( $self, $c ) = @_;
  33
  34             $c->authorization_required_response( realm => "foo" );
  35             $c->error(0);
  36         }
  37
  38 DEPRECATION NOTICE
  39     Please note that this module is DEPRECATED, it has been Superseded by
  40     Catalyst::Authentication::Credential::HTTP, please use that module in
  41     any new projects.
  42
  43     Porting existing projects to use the new module should also be easy, and
  44     if there are any facilities in this module which you cannot see how to
  45     achieve in the new module then *please contact the maintainer* as this
  46     is a bug and *will be fixed*.
  47
  48     Let me say that again: THIS MODULE IS NOT SUPPORTED, use
  49     Catalyst::Authentication::Credential::HTTP instead.
  50
  51 DESCRIPTION
  52     This moduule lets you use HTTP authentication with
  53     Catalyst::Plugin::Authentication. Both basic and digest authentication
  54     are currently supported.
  55
  56     When authentication is required, this module sets a status of 401, and
  57     the body of the response to 'Authorization required.'. To override this
  58     and set your own content, check for the "$c->res->status == 401" in your
  59     "end" action, and change the body accordingly.
  60
  61   TERMS
  62     Nonce
  63         A nonce is a one-time value sent with each digest authentication
  64         request header. The value must always be unique, so per default the
  65         last value of the nonce is kept using Catalyst::Plugin::Cache. To
  66         change this behaviour, override the
  67         "store_digest_authorization_nonce" and
  68         "get_digest_authorization_nonce" methods as shown below.
  69
  70 METHODS
  71     authorization_required %opts
  72         Tries to "authenticate_http", and if that fails calls
  73         "authorization_required_response" and detaches the current action
  74         call stack.
  75
  76         This method just passes the options through untouched.
  77
  78     authenticate_http %opts
  79         Looks inside "$c->request->headers" and processes the digest and
  80         basic (badly named) authorization header.
  81
  82         This will only try the methods set in the configuration. First
  83         digest, then basic.
  84
  85         See the next two methods for what %opts can contain.
  86
  87     authenticate_basic %opts
  88     authenticate_digest %opts
  89         Try to authenticate one of the methods without checking if the
  90         method is allowed in the configuration.
  91
  92         %opts can contain "store" (either an object or a name), "user" (to
  93         disregard %the username from the header altogether, overriding it
  94         with a username or user %object).
  95
  96     authorization_required_response %opts
  97         Sets "$c->response" to the correct status code, and adds the correct
  98         header to demand authentication data from the user agent.
  99
 100         Typically used by "authorization_required", but may be invoked
 101         manually.
 102
 103         %opts can contain "realm", "domain" and "algorithm", which are used
 104         to build %the digest header.
 105
 106     store_digest_authorization_nonce $key, $nonce
 107     get_digest_authorization_nonce $key
 108         Set or get the $nonce object used by the digest auth mode.
 109
 110         You may override these methods. By default they will call "get" and
 111         "set" on "$c->cache".
 112
 113     get_http_auth_store %opts
 114
 115 CONFIGURATION
 116     All configuration is stored in
 117     "YourApp->config->{authentication}{http}".
 118
 119     This should be a hash, and it can contain the following entries:
 120
 121     store
 122         Either a name or an object -- the default store to use for HTTP
 123         authentication.
 124
 125     type
 126         Can be either "any" (the default), "basic" or "digest".
 127
 128         This controls "authorization_required_response" and
 129         "authenticate_http", but not the "manual" methods.
 130
 131     authorization_required_message
 132         Set this to a string to override the default body content
 133         "Authorization required."
 134
 135 RESTRICTIONS
 136     When using digest authentication, this module will only work together
 137     with authentication stores whose User objects have a "password" method
 138     that returns the plain-text password. It will not work together with
 139     Catalyst::Authentication::Store::Htpasswd, or
 140     Catalyst::Plugin::Authentication::Store::DBIC stores whose "password"
 141     methods return a hashed or salted version of the password.
 142
 143 AUTHORS
 144     Yuval Kogman, "nothingmuch@woobling.org"
 145
 146     Jess Robinson
 147
 148     Sascha Kiefer "esskar@cpan.org"
 149
 150 SEE ALSO
 151     RFC 2617 (or its successors), Catalyst::Plugin::Cache,
 152     Catalyst::Plugin::Authentication
 153
 154 COPYRIGHT & LICENSE
 155             Copyright (c) 2005-2006 the aforementioned authors. All rights
 156             reserved. This program is free software; you can redistribute
 157             it and/or modify it under the same terms as Perl itself.
 158