APACHE 2.4 PORTING NOTES

VERY IMPORTANT!!!

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.

Changes Required to Run Under Apache 2.4

Mod Perl: You need at least "mod_perl" version 2.0.9, which is the first official release to support Apache 2.4.
Apache::Test: 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 AuthCookie Subclass

You must not call authcookie's authorize() method. Authorization is done using AuthzProvider's under Apache 2.4 and these work very different from previous apache versions. If you are simply doing simple things such as "Require user ..." or "Require valid-user" in your "httpd.conf", then you likely do not need an authorization provider at all. Apache 2.4 handles these for you in "mod_authz_user.c".
Related to previous item, you must change every method that was called as a "PerlAuthzHandler" under previous versions to return one of the following values:

Apache2::Const::AUTHZ_DENIED_NO_USER: return this constant if "$r->user" is empty/undefined and you do not wish to allow anonymous access.
Apache2::Const::AUTHZ_DENIED: return this constant if "$r->user" is not authorized for the current request.
Apache2::Const::AUTHZ_GRANTED: return this constant if "$r->user" is authorized for the current request
Apache2::Const::AUTHZ_GENERAL_ERROR: return this constant to indicate an error processing authz requirements.
Apache2::Const::AUTHZ_NEUTRAL: return this constant to indicate a neutral response. It is assumed that another authz provider will be checked in a parent/sibling scope that will return granted or denied.

httpd.conf

Remove all "PerlAuthzHandler" entries. "PerlAuthzHandler" is not necessary in Apache 2.4. If you are doing custom authoriaztion, you need to convert these to "PerlAddAuthzProvider" entries:
Depending on what your "Require" directives say, you may need to add one or more top level "PerlAddAuthzProvider" entires and implement a handler for each one.
If your "Require" directives are simply "valid-user" or "user ..." then you do not need to do this. Apache already provides an authz provider that handles "user" and "valid-user" requirements for you in "mod_authz_user.c".
If you are "Require"'ing anything other than "valid-user" or "user ..." then you will need to write your own Authz Provider method and register it with Apache.
Authz Providers are the Apache 2.4 equivalent of a "PerlAuthzHandler" method. Each one implements a specific requirement. E.g.:
```
 PerlAddAuthzProvider species My::AuthCookieHandler->authz_species
    
```
Will be called to handle a
```
 Require species klingon
    
```
Directive.

It is important to know that Authz Providers are called twice for a request. First, the authz provider is called before authentication has been processed to check for anonymous access. In this method call, "$r->user" is not set (to allow for your handler to allow annonymous access). You are expected to return one of:

AUTHZ_GRANTED: Access is granted and no further authn/authz processing will occur for this request.
AUTHZ_DENIED
AUTHZ_NEUTRAL: The response is "HTTP_FORBIDDEN" (unless neutral is overridden by another provider)
AUTHZ_DENIED_NO_USER: This should be returned if "$r->user" is not set and you do not wish to allow anonymous access. Authentication will be processed, "$r->user" will be set with the current username and your authz provider will be called again.

The second time the authz provider is called, "$r->user" is set and you are expected to return one of:

AUTHZ_GRANTED: The request is allowed
AUTHZ_DENIED: The request is forbidden
AUTHZ_NEUTRAL: The request is forbidden, unless another authz provider returns "AUTHZ_GRANTED". Consult the apache documentation about authorization merging for more info.

You could also return "AUTHZ_GENERAL_ERROR" from any of these to indicate an error processing authz directives and halt processing immediately.

One way to think about these response codes what kind of Require satisfies is in effect:

RequireAll/RequireNone: In this case the priority of responses is:

AUTHZ_GENERAL_ERROR: Processing stops immediately
AUTHZ_DENIED: Processing stops immediately, no siblings are processed. Request is denied.
AUTHZ_DENIED_NO_USER: Process Authentication and try again
AUTHZ_GRANTED: Continue processing siblings.
AUTZ_NEUTRAL: Continue processing siblings.

RequireAny: In this case the priority of responses is:

AUTHZ_GENERAL_ERROR: Processing stops immediately
AUTHZ_GRANTED: Processing stops immediately, no siblings are processed. Request is allowed.
AUTHZ_DENIED_NO_USER: Process Authentication and try again
AUTHZ_DENIED: Continue processing siblings.
AUTZ_NEUTRAL: Continue processing siblings.

Important Internal API Changes for Apache 2.4

authorize() has been removed

You need to use a "PerlAddAuthzProvider" and write an appropriate handler as described above instead. Note that you do not need a "PerlAddAuthzProvider" for "user" or "valid-user" requirements. Apache already handles those internally via "mod_authz_user.c"

${auth_name}Satisfy

Satisfy support is removed as it is no longer needed with Apache 2.4.

You are expected to use "RequireAll" or "RequireAny" instead.

e.g.:

    PerlAddAuthzProvider species Your::AuthCookieHandler->authz_species_handler

    <RequireAll>
      Require valid-user
      Require species klingon
    </RequireAll>

see: <https://httpd.apache.org/docs/2.4/howto/auth.html#reqaccessctrl>

Unauthorized User HTTP Response Code

In Apache 2.4, in "mod_authz_core", if no authz handlers return "AUTHZ_GRANTED", then "HTTP_UNAUTHORIZED" is returned. In previous versions of Apache, "HTTP_FORBIDDEN" was returned. You can get the old behaviour if you want it with:

    # in httpd.conf
    AuthzSendForbiddenOnFailure On

FREQUENTLY ASKED QUESTIONS

Why is my authz method called twice per request?
This is normal behaviour under Apache 2.4. This is to accomodate for authorization of anonymous access. You are expected to return "Apache2::Const::AUTHZ_DENIED_NO_USER" IF "$r->user" has not yet been set if you want authentication to proceed. Your authz handler will be called a second time after the user has been authenticated.
I get an error like "Can't locate object method "requires" via package Apache2::RequestRec ..."
This is because you called "AuthCookie"'s "authorize()" method, which is illegal under Apache 2.4. This could either be because your "AuthCookie" subclass explicitly called "authorize()", or (more likely) because your "httpd.conf" contains a line like:
```
 PerlAuthzHandler My::AuthCookie->authorize
    
```
You should remove lines from "httpd.conf" that call "authorize", and your subclass should not be calling authorize().

If you need to do custom autorization, you need to write an authz provider instead.
My log shows an entry like:
```
 authorization result of Require ...: denied (no + # authenticated user yet)
    
```
These are normal. This happens because the authz provider returned "AUTHZ_DENIED_NO_USER" and the authz provider will be called again after authentication happens.