Apache 2.4 has a VERY different authentication API from previous versions. You will not be able to simply ugrade apache and upgrade AuthCookie in order to migrate to Apache 2.4. You will also need to port your AuthCookie subclass over to the Apache 2.4 API, and update your Apache configuration for Apache 2.4.
This document attempts to help you understand the changes required and how to port your module over to Apache 2.4. If your subclass stopped working when you migrated to Apache 2.4, please make sure you have read and understand everything in this document before filing a bug report.
You need at least mod_perl version 2.0.9, which is the first official release to support Apache 2.4.
mod_perl
You need Apache::Test version 1.39 or later. Previous versions do not define the constant APACHE2_4 which is needed for the test suite.
Your module must inherit from Apache2_4::AuthCookie instead of Apache2::AuthCookie
Apache2_4::AuthCookie
Apache2::AuthCookie
You must change every method that was called as a PerlAuthzHandler under previous versions to return one of the following values:
PerlAuthzHandler
return this constant if $r->user is empty/undefined.
$r->user
return this constant if $r->user is not authorized for the current request.
return this constant if $r->user is authorized for the current request
Replace all PerlAuthzHandler entries with top level PerlAddAuthzProvider entries.
PerlAddAuthzProvider
PerlAuthzHandler is gone in Apache 2.4. It has been replaced with PerlAddAuthzProvider. PerlAddAUthzProvider methods are expected to return one of AUTHZ_DENIED_NO_USER, AUTHZ_GRANTED, or AUTHZ_DENIED. Other return values are not valid. Be sure you have ported your authz methods to return the appropriate constant!
PerlAddAUthzProvider
AUTHZ_DENIED_NO_USER
AUTHZ_GRANTED
AUTHZ_DENIED
Add a PerlAddAuthzProvider directive that calls authz_handler()
authz_handler()
E.g.:
PerlAddAuthzProvider user Sample::Apache2::AuthCookieHandler->authz_handler
Note that you can use something other than user. e.g.: my-user if you have other authentication modules in use that are responsible for Requires user ... directives.
user
my-user
Requires user ...
Remove All Instances of PerlAuthzHandler that call authorize()
E.g.: remove all all instances of:
PerlAuthzHandler Your::AuthCookie::Handler->authorize
In Apache2_4::AuthCookie, authorize() is replaced by authz_handler. authz_handler has a different return type from authorize. Apache expects a return value of one of AUTHZ_GRANTED, AUTHZ_DENIED, or AUTHZ_DENIED_NO_USER.
authorize()
authz_handler
authorize
Satisfy support is removed as it is no longer needed with Apache 2.4.
You can handle other non-user requirements with RequireAll, and additional AuthzProvider handlers:
e.g.:
PerlAddAuthzProvider user Your::AuthCookieHandler->authz_handler PerlAddAuthzProvider species Your::AuthCookieHandler->authz_species_handler <RequireAll> Require valid-user Require species gerbil </RequireAll>
see: https://httpd.apache.org/docs/2.4/howto/auth.html#reqaccessctrl
In Apache 2.4, in mod_authz_core, if no authz_handlers return AUTHZ_GRANTED, then HTTP_UNAUTHORIZED is returned. In previous versions, HTTP_FORBIDDEN was returned. You can get the old behaviour if you want it with:
HTTP_UNAUTHORIZED
HTTP_FORBIDDEN
AuthzSendForbiddenOnFailure On
Why is my authz method called twice per request?
This is normal behaviour under Apache 2.4. You are expected to return Apache2::Const::AUTHZ_DENIED_NO_USER IF $r->user has not yet been set. Your authz handler will be called a second time after the user has been authenticated.
Apache2::Const::AUTHZ_DENIED_NO_USER
add support for mod_auth_socache if possible
To install Apache::AuthCookie, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Apache::AuthCookie
CPAN shell
perl -MCPAN -e shell install Apache::AuthCookie
For more information on module installation, please visit the detailed CPAN module installation guide.