Commit | Line | Data |
826670f9 |
1 | NAME |
ade3b861 |
2 | Catalyst::Plugin::Authentication::Credential::HTTP - Superseded / |
3 | deprecated module providing HTTP Basic and Digest authentication for |
4 | Catalyst applications. |
826670f9 |
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 | |
ade3b861 |
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 | |
826670f9 |
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 | |
ade3b861 |
113 | get_http_auth_store %opts |
114 | |
826670f9 |
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 | |