Single Sign-on for Your Web Applications with Apache and Kerberos
Pages: 1, 2

Setting Up the Web Server

First, you'll have to create a service principal for the Apache server. This service
principal will be named HTTP/hostname@REALM. Our example will be for the host freebsd.wedgie.org, in the w2k.wedgie.org AD domain. The service principal in this case will be HTTP/freebsd.wedgie.org@W2K.WEDGIE.ORG (yes, HTTP needs to be capitalized, as this is the exact service principal that IE will request). This principal will be created in the Active Directory Users and Computers MMC snap-in and the keytab exported via the ktsetup program.

Because Windows usernames cannot contain slashes, you'll have to pick a
username that will be mapped to the HTTP service principal. In this case, we will
create a user named freebsdhttp. The password set for this account will become
the service principal's key, so ensure that the password set for this account is a
secure password.

Once the Windows user has been created, then you can map the user and
export a keytab through the ktpass program. ktpass is not installed by default; it
can be found inside of the support/tool subdirectory of the Windows 2000 Server
installation CD. The ktpass command line we will use for our example is:

The keytab can now be copied from the Windows machine to the Apache server
through some secure means, such as secure copy or using a floppy. We will
place the keytab into the directory /usr/local/apache/etc, but it can be placed
anywhere in the file system. Since the contents of this file are sensitive, it should
be readable only by the user the web server runs as.

Compiling the Apache Module

Now we're ready to install mod_auth_gss_krb5. While the instructions on the
SourceForge page show how to build the module statically inside of Apache at
compile time, most administrators prefer the management flexibility of loadable
Apache modules.

Let's step through how you can compile mod_auth_gss_krb5 as a shared
module.

First, you'll need spnegohelp, which is the mini-SPNEGO library that
Microsoft has released on its web site. This library is included with the module
distribution in the spnegohelp directory. Note that there is a pre-processor define
for __LITTLE_ENDIAN__ by default. Those running on processors with big-
endian byte order, such as PowerPC or Sparc, will have to remove this pre-
processor define from the makefile before building spnegohelp.

Now you're ready to compile the Apache module itself. Note that on the
FreeBSD test machine, I had to remove all references to the log() function in
mod_auth_gss_krb5.c. If these aren't removed, you will get unresolved
references to _log in the server's error log when you load the module .

We'll use apxs, the Apache extension tool, to do the dirty work for us. Assuming
that your Apache is installed into /usr/local/apache and MIT Kerberos has been
installed into /usr/local, then the following command will compile and install the
module into the appropriate location:

Now that apxs has compiled and installed the module, we can add the
appropriate directives inside of our httpd.conf file to require authentication for
certain directories. Inside of a <directory> section, insert the following directives:

The paths to the keytab and the realm name should be changed, of course. Now
start the Apache server.

Configuring the Clients

Our next step is to configure the Windows client. Internet Explorer must be set
up to recognize that our new Apache server is in the Intranet zone, and
instructed to use domain authentication with it. Open up the Internet Options
dialog inside of Internet Explorer. The Security tab contains the security zones
that Internet Explorer recognizes. Click Intranet and click the Sites button. Click
Advanced in the next dialog box, and a third dialog is presented where we can
add sites that will be added to the Intranet zone. Click Add and type in the name
of your Apache server, in this case "freebsd.wedgie.org." Return to the Internet
Options dialog, Security tab. Click the "Custom Level" button for the Intranet
security zone. Ensure that "User authentication - Automatic logon only in intranet zone" is selected (at the bottom of the list). Click OK.

If you're using Internet Explorer 6 or above, one more setting must be tweaked.
Inside of the Internet Options dialog box, Advanced tab, there is a setting named
"Enable Integrated Windows Authentication" inside of the Security group. If this
box is not checked, check the box, and restart the machine. More information on
these browser settings can be found in the Microsoft MSDN library.

Now that everything is set up, it's time to see if everything works. Open IE and
go to the protected URL on the Apache server. If the page displays, then
congratulations! The full Kerberos username of the client will be inserted into the
REMOTE_USER environment variable on the Apache server side, for example
Administrator@W2K.WEDGIE.ORG. A simple PHP script or server-side include
page can be used to verify that the REMOTE_USER is now set.

Troubleshooting

What could go wrong?

First, let's take a look at what could happen on the client side. Ensure that you're
logged in to the Windows domain and have a valid Kerberos TGT. You can also
check to see if IE successfully acquired a service ticket for your Apache server
through kerbtray, included with the Windows Resource Kit.

Next, make sure that you aren't using a proxy to contact your Apache server.
Unfortunately, the Negotiate authentication method does not work through web
proxies. Ensure that if a proxy is set, that an exclusion is made for the Apache
sever (assuming, of course, that the server is reachable directly).

If instead you're getting internal server errors from Apache, you should make
sure that the GssKrb5Keytab and Krb5Keytab directives give the correct path to
the keytab and that it is readable by the web server's user ID. If problems
persist, then there is probably something going wrong with your Kerberos
configuration.

the GSSAPI libraries either can't read or find your keytab, or
your hostname or realm are misconfigured. Make sure that your hostname
is set correctly; both forward and reverse DNS should map to the correct
hostname. Test it out by doing nslookup queries on the Apache server itself. If
your hostname is configured correctly, then ensure that the AD server is
configured as your default_realm in the /etc/krb5.conf file.

Summary

After performing these steps, you now have an Apache web server that can
interoperate with Internet Explorer clients in a Windows domain. Clients who
access the protected area of your Apache web server will transparently pass
their domain credentials to your web server through the use of Kerberos, with no
separate username or password prompts.