Apache module mod_auth_fixup
============================

Apache module mod_auth_fixup uses results of previous authentication
and other phases and checks that user was authenticated, optionally
updating the user identifier with a substring based on regular
expression match.

Possible use is processing result of mod_ssl's operation on Apache 2.2.
Module mod_ssl has SSLVerifyClient require mechanism which sets the
user identifier and it is not proper authentication module to the rest
of Apache HTTP Server internals. That makes it hard to combine
mod_ssl with authorization modules to check additional attributes
of the authenticated user.

Module configuration
--------------------

Let us assume we have mod_ssl configured with client authentication:

    <Location /login>
	SSLVerifyClient require
	SSLVerifyDepth 1
	SSLOptions +StrictRequire
	SSLUserName SSL_CLIENT_S_DN_CN
    </Location>

The access will only be allowed if the client certificate can be
verified by mod_ssl, and the authenticated user identifier will be
the content of client's Subject DN's common name. In access log
we will see the CN value as the user identifier.

Often, there are two issues with that situation:

1) On Apache 2.2, when we try to use the result of such authentication
   for example with Require, like

	Require group admins

   or even plain

	Require valid-user

   we will get an error:

	configuration error:  couldn't perform authentication.
	AuthType not set!

   It's because mod_ssl does not run the standard authentication
   handler.

   By adding

	AuthType Fixup

   to the configuration, mod_auth_fixup takes the role of the
   authentication handler, even if it does not do anything else than
   checking that the result of the mod_ssl operation, the user
   identifier it has left in the internal r->user, set.

   Of course, any other module could have set the user identification,
   not just mod_ssl, and mod_auth_fixup would process it just fine.

2) The Common Name field of the Subject DN is often filled with
   structured information, and for the subsequent authorization phase,
   only a substring of that might be the actual user identification
   in the identity management setup used.

   For that, AuthFixupRegexp directive can specify regular expression
   to match the user identifier against, and substitution string. When
   the user identifier matches, it is the updated with the new value,
   and this new value will be then shown in the access log and
   available to later authorization phases. So for example,

	AuthFixupRegexp userid=(.+?); user$1

   will make sure the user identifier contains substring

	userid=<the-identifier>;

   and the nonempty string between userid= and the first semicolon
   will replace the $1 part in the substitution string. Note that
   the first part of the requirement matched by the above
   AuthFixupRegexp example could be handled by

	SSLRequire %{SSL_CLIENT_S_DN_CN} =~ m/userid=.+?;/

   But there is no way to extract the identifier with SSLRequire (and
   to add Require to it in Apache 2.2).

   When AuthFixupRegexp is not specified, it is effectively equivalent
   to

	AuthFixupRegexp .+ $0

The full example configuration might then be:

    <Location /login>
	SSLVerifyClient require
	SSLVerifyDepth 1
	SSLOptions +StrictRequire
	SSLUserName SSL_CLIENT_S_DN_CN

	AuthType Fixup
	AuthFixupRegexp userid=(.+?); user$1
	Require group admins
    </Location>

Building from sources
---------------------

When building from sources, command

    apxs -i -a -c mod_auth_fixup.c -Wall -pedantic

should build and install the module.

License
-------

Copyright 2015 Jan Pazdziora

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.