This is the second in a series describing how to write an Apache module. If you haven’t yet read Creating a C Apache module on Mac OS X Leopard you might want to do so now.

This article will expand on the original module. The original module wasn’t very useful except as a shell. This one will actually do something.

• It will only run when user-based authentication is requested (even though this version won’t actually ask for a username and password).
• It will make a request to an external server for authorization to go ahead.
• It will deny access if the external server tells it to.

The basic module

In the previous module, I registered the function using ap_hook_fixups. That ran the module on every page request. This time, I’m using ap_hook_check_user_id. This will run the module only when some configuration file tells Apache to ask for a username and password.

Call this file mod_external_auth.c and then compile it:

1. sudo apxs -c -i -a mod_external_auth.c
2. sudo apachectl configtest
3. sudo apachectl graceful

Remember that if you’re using a G5 or an Intel, you might need to add some extra options. See the previous article on apache modules. This is the last time I’ll reference that article, but if you need advice on using the Mac’s webserver, read it.

If you try to view web pages on your server, nothing should change (unless you try to view a page in a password-protected directory). That’s because ap_hook_check_user_id doesn’t run unless there’s something like a .htaccess file telling Apache that this directory is password-protected.

First, add a .htaccess file in your web site’s directory (Sites in Mac OS X, or most likely public_html in Linux). It should have only “require valid-user” in it.

Depending on your installation, that might be all you need to do. Type “curl --head http://127.0.0.1/~USER/”, where USER is your username on your computer. If it comes back with “503 Service Temporarily Unavailable” you’re set. If it doesn’t, you need to edit your httpd.conf file. On Mac OS X Leopard, it is in /etc/apache2/httpd.conf. You may find it easiest to add a new configuration file in your home directory somewhere, perhaps Documents/Apache, and call it “custom.conf”. At the bottom of your httpd.conf file, add:

In your custom.conf, put:

Replace Sites with public_html if that’s where your user sites are stored. Replace /Users with wherever your user directories are stored.

Now, when you use curl to view your web page, you should get a 503 error. You should get the same thing if you view it in a graphical browser, something like “Service Temporarily Unavailable”.

You get that error because that’s what the module automatically returns: HTTP_SERVICE_UNAVAILABLE.

Only run when needed

There are different kinds of authentication in Apache. I only want this one to be called when I ask for it. Add “AuthType Hoboes” to the top of the .htaccess file. That will be the trigger to call this module. In the module, replace externalAuthorizer with:

In the list of includes, add:

This version of the function checks what the current auth_type is; if it is not “hoboes” (and we let it be case-insensitive because that’s how .htaccess files are supposed to work), the function returns DECLINE, that is, it declines to handle authorization for this page. Some other module will have to handle it, or the page will fail in some way.

Compile the module. When you use curl to view your web site’s headers, it should now come back with “403 Forbidden”. If you remove the AuthType line from the .htaccess file, it should come back as “500 Internal Server Error”. If you change AuthType to something other than “hoboes”, such as “hoboesx”, it should come back as “401 Authorization Required”.

Constructing the authentication URL

Put AuthType back to hoboes.

Presumably (hopefully!) you have been doing this testing on a development server, such as your desktop Macintosh. Now, go to your real server and somewhere on it add a file called “authorization.php”. For now, just put “No” in it, and nothing else.

Add apr_strings.h to the list of your include files:

Add this function above the externalAuthorizer function:

This function is going to create the authorization request. Replace my URL (hoboes.com…) with the URL to your authorization.php file. The authorization request will send the server the IP of the client making the request, and the page it is making the request for. Of course, for the moment that won’t matter because authorization.php is always going to say “No”.

Now, call makeAuthRequest in externalAuthorizer. Here is the new externalAuthorizer, with the new or changed stuff emphasized:

Note that the HTTP_FORBIDDEN has been replaced with HTTP_MOVED_TEMPORARILY. If you go to http://127.0.0.1/~USER/ in your browser, you should be redirected to your authorization.php file, which will just say “No”.

Authenticate!

Now comes the fun part. In makeAuthRequest, replace the authorization.php apr_pstrcat line with:

Why? Because the next step is to make a function that calls that URL, and as far as I can tell there is no “apr_get_url” to call a complete URL and get the response. The module will have to carefully construct a “socket” to the server and make the file request separately.

Add an include that makes logging easier:

In order to log errors, add a log function:

The ap_log_error function will put an error message in the server’s error log, often in /var/log/apache2/error_log.

Now comes the big function:

This function:

1. Creates an Internet socket to the specified host;
2. Sets the timeout to five seconds;
3. Connects to the socket;
4. Sends the authentication request;
5. Gets the authentication response.

If any of those steps run into an error, it returns an error 503 and logs it.

Finally, externalAuthorizer needs to call the authenticate function and parse the response:

I’ve emphasized the new/changed lines.

Now when you curl your web page or view it in a browser, you should see an error 403 Forbidden. If you switch authorize.php on the external server to say “Yes” instead of “No”, pages should now be allowed. And if you make it reply other than Yes or No, it will go back to error 503.

Further tests

You might test making it dynamic: refuse authorization except during certain parts of the day, or allow authorization to a specific list of client IP addresses. A simple PHP script might look like this:

You will also want to test the error log functionality by putting a bad IP address in the source code (such as adding an “x” to one of the numbers) or disconnecting yourself from the Internet. You should get back a 503 error, and the error_log file should contain an error from the module.

Note that while this module might actually have some uses, remember that the hook hooks it into user authentication. If you don’t use it for user authentication, you’ll want to research what the correct hook is for the kind of authentication you’re doing.