The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Apache-AuthCookie-3.28
River stage one • 9 direct dependents • 9 total dependents
2 ++
/ README.apache-2.4

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.