Configure mod_ntlm for Apache 2, Tomcat, PHP

mod_ntlm Set Up For Apache 2,
Including Integration with
Tomcat and PHP

This document aims to assemble information from a variety of sources in an effort to consolidate answers to the many possible gotchas that might make for a long day of configuring mod_ntlm for Apache 2.x. Specifically, this document deals with mod_ntlm2.

The Obvious First Step: Install It.

Download mod_ntlm2: get either the tarball or an rpm. They are available on sourceforge. I started here, but that document does not spell out some of the pitfalls of configuration.

Assuming that you got the tarball (the extension on the sourceforge download is .gz), unpack it with the tar command:

tar -zxvf mod_ntlm2-0.1.gz

"cd" to the newly created directory, which in the case above is called "mod_ntlm2-0.1". Use "make" to compile the module.

make install

That should put the complied module in the right place. The module is called "mod_ntlm.so" and it should be in the "modules" directory for Apache. In my case, on a RedHat Enterprise 3 install, this is /etc/httpd/modules. Check to make sure that the file is there. (The "make install" that you did might have put it elsewhere. The point is that when you set up httpd.conf to load the module, you have to point it to the right place. Just make sure that you know where the module is.)

The make that you did *might* have created the correct entries in your httpd.conf file. Check this out by opening the file (use vi: it's good for you). Ok ok, how about gedit for the nice fonts:

gedit /etc/httpd/conf/httpd.conf

... or wherever you have Apache installed. Search for "LoadModule ntlm_module" and you should find the following line:

LoadModule ntlm_module modules/mod_ntlm.so

If you do not find this line, then look for "LoadModule" and add this line after all the other LoadModule lines.

The purpose of this is to make the module available to Apache. Notice, at this point, NTLM authentication will not actually work. You still have to tell Apache how to use mod_ntlm.

Configure Apache To Use mod_ntlm

Apache is a pretty flexible monster, so there are many ways to tell it how to use mod_ntlm: e.g., you can use directives in .htaccess files or you can set it up in httpd.conf. In my case, I want to use it always. I achieved that by adding the following at the end of my httpd.conf file (you will need to change certain values, as detailed below):

<Location / >
     AuthType NTLM
     NTLMAuth on
     NTLMAuthoritative on
     NTLMDomain psb
     NTLMServer provident1
     NTLMBackup fs0201
     Require valid-user
</Location>

First off, note that if you want NTLM authentication turned on only in certain directories, you should specify that location. E.g., instead of "/" you might want to use "/blue" (that's my testing place).

The Important Points Of Configuration

You will have to change a few directives in your file. First, your NTLMDomain will be different. In my case, the domain is called "psb" — change yours appropriately. Second, your NTLMServer and NTLMBackup will be different. Find out what they are called on your network and change those values appropriately.

Here's where I got stuck! Do not use a suffix on your NTLMServer and NTLMBackup values. For example, at first I called mine "provident1.provident" and "fs0201.provident" and I got Internal Server Errors. Looking in the Apache logs revealed that there was a problem communicating with the Domain Controller. I found a reference to a similar problem and the suggestion was to NOT use the suffix. Hence, I removed the suffixes and it worked!

Furthermore, if you have problems getting to the domain controllers, try adding them to "/etc/hosts". And, make sure that your firewall is not blocking communication with them.

Review

So the big points are to:

Download the correct version of mod_ntlm
Compile and install it and check the config files
Set up Apache, via the httpd.conf file, to require authentication where desired
Watch out for the little things! Like those suffixes on the domain controllers

Test It

As a test, I created a quick PHP page. Try this:


<html>

<head>
<style type="text/css">
body { background-color: #269; }
p { 
	font-size: 18px;
	font-weight: bold;
	color: #cc0;
}
#thedivision {
	width: 50%;
	left: 25%;
	top: 25%;
	height: 50%;
	background-color: #036;
	position: absolute;
	text-align: center;
	padding: 3% 3% 3% 3%;
}
</style>

</head>

<body>

<div id="thedivision">
<p>
Welcome to the official <i>test</i> PHP page.

<p>
If you see this page, and we're assuming you do if you're
reading this sentence, this implies that PHP is set up
correctly. 

<p>
Moreover, you appear to be logged in as:
<br>
<?php
echo $_SERVER['REMOTE_USER'];
?>

</div>

</body>

</html>

If you want to test integration with Tomcat, then I assume you have already set up Apache to forward requests to Tomcat with mod_jk. (If not, there is a how to in the "Technology" section of this site). Try the same as above as a .jsp instead. Replace the PHP code with:


<%
out.println( request.getRemoteUser() );
%>

Good Luck!!

Sorrell
February, 2005

mod_ntlm Set Up For Apache 2, Including Integration with Tomcat and PHP

mod_ntlm Set Up For Apache 2,
Including Integration with
Tomcat and PHP