Apache::AuthenHook - Perl API for Apache 2.1 authentication
PerlLoadModule Apache::AuthenHook
PerlModule My::OtherProvider
<Location /digest>
Require valid-user
AuthType Digest
AuthName realm1
AuthDigestProvider My::DigestProvider file My::OtherProvider::digest
AuthUserFile realm1
</Location>
<Location /basic>
Require valid-user
AuthType Basic
AuthName foorealm
AuthBasicProvider My::OtherProvider::basic file My::BasicProvider
AuthUserFile realm1
</Location>
Apache::AuthenHook offers access to the 2.1 Apache authentication API in Perl.
This is different than the authentication API from Apache 1.3 or even Apache
2.0, but in its differences lies strength.
For a full description of how authentication works in 2.1, see
http://www.serverwatch.com/tutorials/article.php/2202671
Basically, the difference between 2.0 and 2.1 is that authentication is now
delegated to providers, and each provider has a specific purpose. For
instance, mod_authn_file covers gleaning the password from an .htpasswd or
.htdigest file, while mod_auth_basic covers the Basic dialogue between the
client and server, regardless of the source of the password. The best part of
all this (to me) is that Digest authentication is also delegated out -
mod_auth_digest now handles all the intricacies of Digest authentication
(including the elusive MSIE support) which means you don't need to worry about
them (and neither do I). All that Digest authentication requires is *some*
authentication provider to provide user credentials - this can be via
mod_authn_file or another mechanism of your choosing.
Apache::AuthenHook registers and coordinates the use of Perl handlers as
authentication providers.
How does this affect you? Read on...
Say you want to enable Digest authentication in your Apache 2.1 server...
PerlLoadModule Apache::AuthenHook
<Location /digest>
Require valid-user
AuthType Digest
AuthName realm1
AuthDigestProvider My::DigestProvider file
AuthUserFile realm1
</Location>
This configuration means that My::DigestProvider will be responsible for
providing user credentials for requests to /digest. if My::DigestProvider
finds a suitable user, mod_auth_digest will verify those credentials and take
care of setting all the proper headers, set the proper HTTP response status,
and so on. If My::DigestProvider cannot find a matching user it can decide
what to do next - either pass the user to the next provider (in this case the
default file provider, which will use the flat file "realm1") or
decide that no user means no access.
Here is a simple My::DigestProvider
use Apache2::Const -compile => qw(OK DECLINED HTTP_UNAUTHORIZED);
sub handler {
my ($r, $user, $realm, $hash) = @_;
# user1 at realm1 is found - pass to mod_auth_digest
if ($user eq 'user1' && $realm eq 'realm1') {
$$hash = 'eee52b97527306e9e8c4613b7fa800eb';
return Apache2::Const::OK;
}
# user2 is denied outright
if ($user eq 'user2' && $realm eq 'realm1') {
return Apache2::Const::HTTP_UNAUTHORIZED;
}
# all others are passed along to the next provider
return Apache2::Const::DECLINED;
}
isn't that easy?
the only thing that is a bit tricky here is $$hash. the fourth argument passed
to your handler, $hash, is a reference to to a simple scalar that needs to be
populated with the MD5 hash of the user:realm:password combination you
determine for the incoming user. this may seem a bit strange, but it is
actually exactly how things work over in Apache C land, so I guess that makes
it ok.
as you can see, returning OK means "user found" and requires that
$$hash be populated - mod_auth_digest will take care of determining whether
the hash matches the incoming Digest criteria. returning HTTP_UNAUTHORIZED
(which is the same as the former and still available AUTH_REQUIRED constant)
means "no access." returning DECLINED means "some other
provider can try."
The steps are remarkably similar for Basic authentication, first
<Location /basic>
Require valid-user
AuthType Basic
AuthName foorealm
AuthBasicProvider My::BasicProvider file
AuthUserFile realm1
</Location>
then
use Apache2::Const -compile => qw(OK DECLINED HTTP_UNAUTHORIZED);
sub handler {
my ($r, $user, $password) = @_;
# user1/basic1 is ok
if ($user eq 'user1' && $password eq 'basic1') {
return Apache2::Const::OK;
}
# user2 is denied outright
if ($user eq 'user2') {
return Apache2::Const::HTTP_UNAUTHORIZED;
}
# all others are passed along to the next provider
return Apache2::Const::DECLINED;
}
In the case of Basic authentication, the return codes mean essentially the same
thing. The one exception is that OK means that you have checked the user
against the password and have found that they match (as opposed to with
Digest, where the actual verification is not done by you).
These explanations should be enough to get you going - see the files in the test
suite for more examples.
This has been tested under the prefork MPM only, using mostly Perl 5.9.0 (as
well as some 5.8.0). It will not work under threaded MPMs - soon, just not
yet.
This is very much so alphaware, so beware - bugs may lurk in unexpected places.
there is one bug that is outside of my control, though, and concerns MSIE and
Digest authentication for URIs that include query strings. see
http://httpd.apache.org/docs-2.0/mod/mod_auth_digest.html
one workaround for this issue is is to use POST instead of GET for your forms.
A limitation of this interface is that you can't use Perl providers that are not
at least two levels deep - the criterion for registering a Perl provider is a
simple check for a double-colon. for example, My::Provider will work while
Provider won't (although Provider::handler will). anyway, single level
handlers are rare, so fixing it would be a lot of trouble for little benefit.
Geoffrey Young <
[email protected]>
Copyright (c) 2003, Geoffrey Young
All rights reserved.
This module is free software. It may be used, redistributed and/or modified
under the same terms as Perl itself.