Debian Codegraph @

README

raw
1 NAME
2
3 Apache::AuthenHook - Perl API for Apache 2.1 authentication
4
5 SYNOPSIS
6
7 PerlLoadModule Apache::AuthenHook
8
9 PerlModule My::OtherProvider
10
11 <Location /digest>
12 Require valid-user
13 AuthType Digest
14 AuthName realm1
15
16 AuthDigestProvider My::DigestProvider file My::OtherProvider::digest
17
18 AuthUserFile realm1
19 </Location>
20
21 <Location /basic>
22 Require valid-user
23 AuthType Basic
24 AuthName foorealm
25
26 AuthBasicProvider My::OtherProvider::basic file My::BasicProvider
27
28 AuthUserFile realm1
29 </Location>
30
31 DESCRIPTION
32
33 Apache::AuthenHook offers access to the 2.1 Apache authentication
34 API in Perl. This is different than the authentication API
35 from Apache 1.3 or even Apache 2.0, but in its differences lies
36 strength.
37
38 For a full description of how authentication works in 2.1, see
39
40 http://www.serverwatch.com/tutorials/article.php/2202671
41
42 Basically, the difference between 2.0 and 2.1 is that authentication
43 is now delegated to providers, and each provider has a specific
44 purpose. For instance, mod_authn_file covers gleaning the password
45 from an .htpasswd or .htdigest file, while mod_auth_basic covers
46 the Basic dialogue between the client and server, regardless
47 of the source of the password. The best part of all this (to me)
48 is that Digest authentication is also delegated out -
49 mod_auth_digest now handles all the intricacies of Digest
50 authentication (including the elusive MSIE support) which
51 means you don't need to worry about them (and neither do I).
52 All that Digest authentication requires is *some* authentication
53 provider to provide user credentials - this can be via
54 mod_authn_file or another mechanism of your choosing.
55
56 Apache::AuthenHook registers and coordinates the use of Perl
57 handlers as authentication providers.
58
59 How does this affect you? Read on...
60
61 EXAMPLE
62
63 Say you want to enable Digest authentication in your Apache 2.1 server...
64
65 PerlLoadModule Apache::AuthenHook
66
67 <Location /digest>
68 Require valid-user
69 AuthType Digest
70 AuthName realm1
71
72 AuthDigestProvider My::DigestProvider file
73
74 AuthUserFile realm1
75 </Location>
76
77 This configuration means that My::DigestProvider will be
78 responsible for providing user credentials for requests to
79 /digest. if My::DigestProvider finds a suitable user,
80 mod_auth_digest will verify those credentials and take care of
81 setting all the proper headers, set the proper HTTP response
82 status, and so on. If My::DigestProvider cannot find a matching
83 user it can decide what to do next - either pass the user to
84 the next provider (in this case the default file provider,
85 which will use the flat file "realm1") or decide that no user
86 means no access.
87
88 Here is a simple My::DigestProvider
89
90 use Apache2::Const -compile => qw(OK DECLINED HTTP_UNAUTHORIZED);
91
92 sub handler {
93
94 my ($r, $user, $realm, $hash) = @_;
95
96 # user1 at realm1 is found - pass to mod_auth_digest
97 if ($user eq 'user1' && $realm eq 'realm1') {
98 $$hash = 'eee52b97527306e9e8c4613b7fa800eb';
99 return Apache2::Const::OK;
100 }
101
102 # user2 is denied outright
103 if ($user eq 'user2' && $realm eq 'realm1') {
104 return Apache2::Const::HTTP_UNAUTHORIZED;
105 }
106
107 # all others are passed along to the next provider
108 return Apache2::Const::DECLINED;
109 }
110
111 isn't that easy?
112
113 the only thing that is a bit tricky here is $$hash. the fourth
114 argument passed to your handler, $hash, is a reference to
115 to a simple scalar that needs to be populated with the MD5 hash of
116 the user:realm:password combination you determine for the
117 incoming user. this may seem a bit strange, but it is actually
118 exactly how things work over in Apache C land, so I guess that
119 makes it ok.
120
121 as you can see, returning OK means "user found" and requires
122 that $$hash be populated - mod_auth_digest will take care
123 of determining whether the hash matches the incoming Digest
124 criteria. returning HTTP_UNAUTHORIZED (which is the same
125 as the former and still available AUTH_REQUIRED constant)
126 means "no access." returning DECLINED means "some other provider
127 can try."
128
129 The steps are remarkably similar for Basic authentication, first
130
131 <Location /basic>
132 Require valid-user
133 AuthType Basic
134 AuthName foorealm
135
136 AuthBasicProvider My::BasicProvider file
137
138 AuthUserFile realm1
139 </Location>
140
141 then
142
143 use Apache2::Const -compile => qw(OK DECLINED HTTP_UNAUTHORIZED);
144
145 sub handler {
146
147 my ($r, $user, $password) = @_;
148
149 # user1/basic1 is ok
150 if ($user eq 'user1' && $password eq 'basic1') {
151 return Apache2::Const::OK;
152 }
153
154 # user2 is denied outright
155 if ($user eq 'user2') {
156 return Apache2::Const::HTTP_UNAUTHORIZED;
157 }
158
159 # all others are passed along to the next provider
160 return Apache2::Const::DECLINED;
161 }
162
163 In the case of Basic authentication, the return codes mean
164 essentially the same thing. The one exception is that OK
165 means that you have checked the user against the password
166 and have found that they match (as opposed to with Digest,
167 where the actual verification is not done by you).
168
169 These explanations should be enough to get you going -
170 see the files in the test suite for more examples.
171
172 NOTES
173
174 This has been tested under the prefork MPM only, using
175 mostly Perl 5.9.0 (as well as some 5.8.0). It will not
176 work under threaded MPMs - soon, just not yet.
177
178 FEATURES/BUGS
179
180 This is very much so alphaware, so beware - bugs may lurk
181 in unexpected places. there is one bug that is outside
182 of my control, though, and concerns MSIE and Digest
183 authentication for URIs that include query strings. see
184
185 http://httpd.apache.org/docs-2.0/mod/mod_auth_digest.html
186
187 one workaround for this issue is is to use POST instead of
188 GET for your forms.
189
190 A limitation of this interface is that you can't use Perl
191 providers that are not at least two levels deep -
192 the criterion for registering a Perl
193 provider is a simple check for a double-colon.
194 for example, My::Provider will work while Provider won't
195 (although Provider::handler will). anyway, single
196 level handlers are rare, so fixing it would be a lot
197 of trouble for little benefit.
198
199 AUTHOR
200
201 Geoffrey Young E<lt>[email protected]<gt>
202
203 COPYRIGHT
204
205 Copyright (c) 2003, Geoffrey Young
206
207 All rights reserved.
208
209 This module is free software. It may be used, redistributed
210 and/or modified under the same terms as Perl itself.