Commit | Line | Data |
826670f9 |
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 | |