README.apache-2.4(3)

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.