README

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