=head1 APACHE 2.4 PORTING NOTES

=head2 VERY IMPORTANT!!!

Apache 2.4 has a B<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.

=head2 Changes Required to Run Under Apache 2.4

=over 4

=item Mod Perl

You need at least C<mod_perl> version 2.0.9, which is the first official
release to support Apache 2.4.

=item 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.

=item Your AuthCookie Subclass

=over 4

=item *

Your module must inherit from C<Apache2_4::AuthCookie> instead of C<Apache2::AuthCookie>

=item *

You must change every method that was called as a C<PerlAuthzHandler> under
previous versions to return one of the following values:

=over 4

=item Apache2::Const::AUTHZ_DENIED_NO_USER

return this constant if C<< $r->user >> is empty/undefined.

=item Apache2::Const::AUTHZ_DENIED

return this constant if C<< $r->user >> is not authorized for the current request.

=item Apache2::Const::AUTHZ_GRANTED

return this constant if C<< $r->user >> is authorized for the current request

=back

=back

=item httpd.conf

=over 4

=item *

Replace all C<PerlAuthzHandler> entries with top level C<PerlAddAuthzProvider> entries.

C<PerlAuthzHandler> is gone in Apache 2.4.  It has been replaced with
C<PerlAddAuthzProvider>.  C<PerlAddAUthzProvider> methods are expected to
return one of C<AUTHZ_DENIED_NO_USER>, C<AUTHZ_GRANTED>, or C<AUTHZ_DENIED>.
Other return values are not valid.  Be sure you have ported your authz methods
to return the appropriate constant!

=item *

Add a C<PerlAddAuthzProvider> directive that calls C<authz_handler()>

E.g.:

    PerlAddAuthzProvider user Sample::Apache2::AuthCookieHandler->authz_handler

Note that you can use something other than C<user>.  e.g.: C<my-user> if you
have other authentication modules in use that are responsible for
C<Requires user ...> directives.

=item *

Remove All Instances of PerlAuthzHandler that call authorize()

E.g.: remove all all instances of:

    PerlAuthzHandler Your::AuthCookie::Handler->authorize

=back

=back

=head2 Important Internal API Changes for Apache 2.4

=over 4

=item authorize() has been removed

In C<Apache2_4::AuthCookie>, C<authorize()> is replaced by C<authz_handler>.
C<authz_handler> has a different return type from C<authorize>.  Apache expects
a return value of one of C<AUTHZ_GRANTED>, C<AUTHZ_DENIED>, or
C<AUTHZ_DENIED_NO_USER>.

=item ${auth_name}Satisfy

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

=item Unauthorized User HTTP Response Code

In Apache 2.4, in mod_authz_core, if no authz_handlers return C<AUTHZ_GRANTED>,
then C<HTTP_UNAUTHORIZED> is returned.  In previous versions, C<HTTP_FORBIDDEN>
was returned.  You can get the old behaviour if you want it with:

    AuthzSendForbiddenOnFailure On

=back

=head1 FREQUENTLY ASKED QUESTIONS

=over 4

=item *

Why is my authz method called twice per request?

This is normal behaviour under Apache 2.4.  You are expected to return
C<Apache2::Const::AUTHZ_DENIED_NO_USER> IF C<< $r->user >> has not yet been
set.  Your authz handler will be called a second time after the user has been
authenticated.

=back

=head1 TODO

=over 4

=item *

add support for mod_auth_socache if possible

=back
