Kerberos v4 Apache module
Author: Dug Song <dugsong@UMICH.EDU>
Overview
Protocol
-
Client -> Server: unauthenticated request
Server -> Client: auth challenge (specify Kerberos v4)
Client -> Server: auth response (request+ticket+HMAC-MD5)
Server -> Client: protected page
The full details can be had here. We can only hope for widespread adoption of Kerberized TLS in the future, to obviate the need for such kludging around as this (I've added Kerberos v4 support to the Netscape SSLref implementation; expect to see a generic server proxy and local client proxy soon!).
Installation
-
mod_auth_krb4.csource file
Apache (or Stronghold, or Apache-SSL) distribution (tested against versions 1.2.1 and 2.0)
Kerberos v4 distribution (MIT, Cygnus, KTH, etc.)
AFS distribution (optional)
Step 1
For Apache: Unpack the Apache distribution and copy this module (mod_auth_krb4.c) into the
src directory. Apply this patch to the Configuration
file. If building for Apache-SSL, get rid of -ldes from
KRB4LIB in the patched Configuration file, and make sure the
SSL_LIBS come after the AFS and Kerberos libs in
LIBS in the Makefile.tmpl after applying the
SSLpatch - it should be in the make target for httpsd.
For Stronghold: Unpack the Stronghold distribution for your platform
(e.g. stronghold-2.0-platform.tar.gz) and copy this module
(mod_auth_krb4.c) into the
apache directory. Now create the following symlinks:
-
cd stronghold-2.0/apache
ln -s ../serv-root/dist/Configuration .
ln -s ../binary/platform/obj/libmodssl.a .
ln -s ../binary/platform/obj/libfcgi.a .
cd ..
ln -s binary/platform/ssl ssl
And apply this patch to
the Configuration file.
Step 2
Substitute the correct paths to your Kerberos v4 and AFS installations in the patchedConfiguration file. Add -lc
/usr/ucblib/libucb.a to the end of AFSLIB if
you're building on Solaris.
Now run the Configure script, which should produce a sane
Makefile. Run make. Everything should have
built correctly. If not, fix it. For Apache, you can now do a
make install. For Stronghold,
cp httpsd ../binary/platform/httpsd and run
INSTALL.sh
Step 3
Make sure you have a valid srvtab for the principal you specify (see below), and that the srvtab file is readable by the httpd server (usually runs asnobody). You should create a new service
principal and srvtab just for your server,
ex. www.lukyduk@UMICH.EDU in
/usr/local/www/srvtab.www. If you see lots of
krb_rd_req() messages in your error_log,
check for bad permissions on the srvtab file or a bogus srvtab entry.
Step 4
Add the following lines to yourhttpd.conf, substituting
the real name and location of your server's Kerberos principal and
srvtab. Make sure the srvtab is readable by the httpd process (usually
runs as nobody).
-
# Kerberos v4 authentication support KerberosV4Principal www.lukyduk@UMICH.EDU KerberosV4Srvtab /usr/local/www/srvtab.www BrowserMatch Mozilla use_kerberos_plugin BrowserMatch Win windows_netscape_bogosity AddType application/x-kerberos4-mime krb4
Configuration
.htaccess file in the directory being protected (for
.htaccess files to work, you need at least AllowOverride
AuthConfig in your server config files). For example, to protect all
URLs in /www/private, have
in /www/private/.htaccess: AuthType KerberosV4 require user dugsong require group itd.gpcc |
or in /www/conf/httpd.conf: <Directory /www/private> AuthType KerberosV4 require user dugsong require group itd.gpcc </Directory> |
-
require valid-user specifies any user in the local realm.
require user [users...] specifies a list of Kerberos principal names.
and if compiled with AFS support,
-
require group [groups...] specifies a list of AFS PTS groups.
require afs-acl-check specifies that authorization for the authenticated user will be based on the existing AFS filesystem ACLs for the directory of the requested document. The HTTP server needs to have
rl(read, lookup) permissions on the directory (your server can have an AFS token viareauth- see /afs/transarc.com/public/afs-contrib/tools/reauth for more info). If the directory isn't in AFS and this is enabled, the user will always be allowed.
In addition, the following Kerberos authentication directives may
appear anywhere in server configuration files or
.htaccess (except for KerberosV4Principal and
KerberosV4Srvtab, which can only be in the server config files). They
are allowed within <Directory>
or <VirtualHost]
directives, so that document trees on the same server may be protected
under different Kerberos realms or be restricted under different
security policies:
KerberosV4Principal [service.host@REALM] specifies the Kerberos
v4 service principal the client should present tickets for. Required.
KerberosV4Srvtab [/path/to/srvtab] specifies the Kerberos v4 srvtab file to use. This file should be readable by the httpd uid. Required.
KerberosV4ErrorDocument [/path/to/page.html] specifies the document that should be returned to clients upon authentication failure. This document should NOT have the terminating </BODY> and </HTML> end tags - this is to allow for the addition of an error message by the server. If not specified, server uses compiled-in default. Optional.
KerberosV4EnforceHMAC [on|off] specifies that the server will require a valid HMAC on the requested URL; this is STRONGLY recommended if building without SSL support. Enforcing a correct HMAC will require protected inlined images in a restricted page to be in the same directory as that page, however. Default is off. Optional.
KerberosV4PluginVersion [version number] specifies the minimum client plug-in version to accept requests from; otherwise, prompt the user to upgrade to the latest plug-in version. Default is off. Optional.
KerberosV4RequiresSSL [on|off] (only for Stronghold/Apache-SSL) specifies that the server will only accept Kerberos v4 authentication for protected pages over SSL; unencrypted connections will be refused authorization. Recommended setting is on. Default is off. Optional.
AllowClientCaching [on|off] specifies whether or not the server will send back "Pragma: no-cache" and "Cache-Control: no-cache" directives to prevent the client from caching protected documents. Default is off, but it may be useful to turn on within image directories, etc. Optional.