Configuration

This page describes configuration of module version 5.0. Configuration guide for the older module 4.x can be found here.

Before starting configuring the module make sure your Kerberos enviroment is properly configured (i.e. KDC, /etc/krb5.conf, etc.). The easiest way to check is using the kinit command from the apache machine to get a ticket for some known principal (preferably that one who will be used to test the module).

Now you have to create an service key for the module, which is needed to perform client authentication. Verification of the kerberos password has two steps. In the first one the KDC is contacted using the password trying to receive a ticket for the client. After this ticket is sucessfuly acquired, the module must also verify that KDC hasn't been deliberately faked and the ticket just received can be trusted. If this check would haven't been done any attacker capable of spoofing the KDC could impersonate any principal registered with the KDC. In order to do this check the apache module must verify that the KDC knows its service key, which the apache shares with the KDC. This service key must be created during configuration the module. This service key is also needed when the Negotiate method is used. In this case the module acts as a standard kerberos service (similarly to e.g. kerberized ssh or ftp servers). Default name of the service key is HTTP/<fqdn_of_www_server>@REALM, another name of the first instance can be set using the KrbServiceName option. The key must be stored in a keytab on a local disk, the Krb5Keytab and Krb4Srvtab options are used to specify the filename with the keytab. This file should be only readable for the apache process and contain only the key used for www authentication.

In order to get the module loaded on start of apache add following line to your httpd.conf:

	LoadModule	auth_kerb_module	libexec/mod_auth_kerb.so

Summary of Supported Directives

For Kerberos authentication to work, AuthType must be set to

• Kerberos

To enable or disable the use of the Negotiate method. You need a special support on the browser side to support this mechanism.

To enable or disable the use of password based authentication for Kerberos v5.

To enable or disable the use of password based authentication for Kerberos v4.

If set to off this directive allow authentication controls to be pass on to another modules. Use only if you really know what you are doing.

This option takes one or more arguments (separated by spaces), specifying the Kerberos realm(s) to be used for authentication. This defaults to the default realm taken from the local Kerberos configuration.

This option can be used to disable the verification tickets against local keytab to prevent KDC spoofing atacks. It should be used only for testing purposes. You have been warned.

For specification the service name that will be used by Apache for authentication. Corresponding key of this name must be stored in the keytab.

This option takes one argument, specifying the path to the Kerberos V4 srvtab. It will simply use the "default srvtab" from Kerberos V4's configuration if this option is not specified. The srvtab must be readable for the apache process, and should be different from srvtabs containing keys for other services.

This option takes one argument, specifying the location of the Kerberos V5 keytab file. It will use the "default keytab" from Kerberos V5's config if it is not specified here. The keytab file must be readable for the apache process, and should be different from other keytabs in the system.

This option enables credential saving functionality.

Ticket File/Credential Cache Saving

Sometimes there is need to keep the ticket file or credential cache around after a user authenticates, normally for cgi scripts. If you turn on KrbSaveCredentials, the tickets will be retrieved into a ticket file or credential cache that will be available for the request handler. The ticket file will be removed after request is handled.

A CGI script can use these files by setting the KRB5CCNAME (v5) or KRBTKFILE (v4) environment variables to point to the filename as listed above. A sample script to use the KRB5CCNAME is here.

Sample .htaccess

	AuthType Kerberos
	AuthName "Kerberos Login"
	KrbAuthRealms KRB.NCSU.EDU NCSU.EDU
	KrbMethodK4Passwd off
	require user principal1@KRB.NCSU.EDU principal2@NCSU.EDU

Using Mozilla

The module was tested with the latest Mozilla 1.7b which supports GSSAPI authentication in the default distribution for Linux. If you want to give it a try download the mozilla package. If you're using the MIT implementation of krb5 all you have to do is to make sure that the MIT dynamic libraries are available for Mozilla. They must be either installed in a system directories or set the LD_LIBRARY_PATH enviroment variable to point to the directory containing the libraries.

If you're using the Heimdal krb5 implementation, you have to install an additional package with dummy libraries. Download and unpack it. Enter the gss_dummy directory and run make. Then add full path to the directory to the LD_LIBRARY_PATH enviroment variable as well as path to your standard Heimdal libraries. Then set the LD_PRELOAD variable to point to Heimdal libgssapi.so and to the libgss_nt_service_name.so library created in the dummy directory

When you set up your enviroment and export the variables you can start the Mozilla and should be able to talk to the module. You can also enable debugging of the Mozilla Negotiate module by setting the NSPR_LOG_MODULES and NSPR_LOG_FILE variables to negotiateauth:5 and /tmp/negotiateauth.log respectively.