diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 135 |
1 files changed, 135 insertions, 0 deletions
@@ -0,0 +1,135 @@ + +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. + |