Rate this page

Configure Apache to use Kerberos authentication

Tested on

Debian (Lenny, Squeeze)
Ubuntu (Lucid)


To configure Apache to use Kerberos authentication


Kerberos is an authentication protocol that supports the concept of Single Sign-On (SSO). Having authenticated once at the start of a session, users can access network services throughout a Kerberos realm without authenticating again. For this to work it is necessary to use network protocols that are Kerberos-aware.

In the case of HTTP, support for Kerberos is usually provided using the SPNEGO authentication mechanism (Simple and Protected GSS-API Negotiation). This is also known as ‘integrated authentication’ or ‘negotiate authentication’. Apache does not itself support SPNEGO, but support can be added by means of the mod_auth_kerb authentication module.


Suppose you wish to restrict access to the web site http://www.example.com/. Authentication is to be performed using Kerberos and SPNEGO. The web site need not be accessible to non-SPNEGO-enabled web browsers.

The users to be given access are members of the Kerberos realm EXAMPLE.COM and are named dougal, brian, ermintrude and dylan. The realm can be administered using the principal bofh/admin.


The description below assumes that you have already installed both Apache and Kerberos on the web server.

Apache should be in a state where you can request at least one page from the relevant web site for testing purposes. It need not contain any real content (and if it does then you will probably want to take steps to isolate the server from unauthorised users until it has been properly secured).

Kerberos should be in a state where EXAMPLE.COM has been configured as the default realm and it is possible to obtain a ticket for that realm on the web server.



The method described here has six steps:

  1. Install the mod_auth_kerb authentication module.
  2. Create a service principal for the web server.
  3. Create a keytab for the service principal.
  4. Specify the authentication method to be used.
  5. Specify a list of authorised users.
  6. Reload the Apache configuration.

Note that in addition to enabling SPNEGO on the web server, it may also be necessary to explicitly enable it within the web browser. This is known to be the case for Mozilla Firefox. See:

Install the mod_auth_kerb authentication module

As noted above, Apache does not itself provide support for SPNEGO but it can be added using the module mod_auth_kerb. This is included in most major GNU/Linux distributions, but because it is a third-party module it is usually packaged separately from Apache. On Debian-based systems it is provided by the package libapache2-mod-auth-kerb:

apt-get install libapache2-mod-auth-kerb

and on Red Hat-based systems by the package mod_auth_kerb:

yum install mod_auth_kerb

Apache modules must be loaded before they can be used, but both of the above packages arrange for this to happen automatically. If for any reason you need to do this manually then the appropriate configuration directive is:

LoadModule auth_kerb_module /usr/lib/apache2/modules/mod_auth_kerb.so

(where the pathname of the module should be replaced with whatever is appropriate for your system).

Create a service principal for the web server

SPNEGO requires that a Kerberos service principal be created for the web server. The service name is defined to be HTTP, so for the server www.example.com the required service principal name is HTTP/www.example.com@EXAMPLE.COM.

If you are using MIT Kerberos then the service principal can be created using the kadmin command:

kadmin -p bofh/admin -q "addprinc -randkey HTTP/www.example.com"

See the microHOWTO Create a service principal using MIT Kerberos for further information about how a service principal can be created and why one is needed.

Create a keytab for the service principal

A keytab is a file for storing the encryption keys corresponding to one or more Kerberos principals. mod_auth_kerb needs one in order to make use of the service principal created above. If you are using MIT Kerberos then the keytab (like the service principal) can be created using the kadmin command. Its ownership must be such that it is readable by the Apache process.

On Debian-based systems a suitable location for the keytab would be /etc/apache2/http.keytab and the appropriate owner is www-data:

kadmin -p bofh/admin -q "ktadd -k /etc/apache2/http.keytab HTTP/www.example.com"
chown www-data /etc/apache2/http.keytab

On Red Hat-based systems a suitable location would be /etc/httpd/http.keytab and the appropriate owner is apache:

kadmin -p bofh/admin -q "ktadd -k /etc/httpd/http.keytab HTTP/www.example.com"
chown apache /etc/httpd/http.keytab

The -k option specifies the pathname to the keytab, which will be created if it does not already exist.

See the microHOWTO Add a host or service principal to a keytab using MIT Kerberos for further information about the creation of keytabs, their purpose, and why the default keytab (typically /etc/krb5.keytab) is not suitable for use by network services that do not run as root.

If you wish to check that the key has been correctly added to the keytab then you can attempt to use it to authenticate as the service principal, then view the resulting ticket-granting ticket using klist:

kinit -k -t /etc/apache2/http.keytab HTTP/www.example.com

Specify the authentication method to be used

Apache must be told which parts of which web sites are to use authentication provided by mod_auth_kerb. This is done using the AuthType directive with a value of Kerberos. Some further directives are then needed to configure how mod_auth_kerb should behave.

If the intent is to apply these directive to the whole of a given web site then they can be placed in a <Location> container with a path corresponding to the root of the site:

<Location />
 AuthType Kerberos
 AuthName "Acme Corporation"
 KrbMethodNegotiate on
 KrbMethodK5Passwd off
 Krb5Keytab /etc/apache2/http.keytab

The AuthName directive specifies the HTTP authorisation realm. Its purpose is to indicate to the user which of the various passwords he might know is needed to gain access to a particular web site. With true Kerberos authentication there should be no password prompt, and mod_auth_kerb appears to work perfectly well without an AuthName having been specified; however the Apache documentation states that it is required, so it would seem prudent to supply one anyway. A suitable value might be the domain name, the name of the Kerberos realm, or the name of the organisation to which the web site belongs.

In addition to the SPNEGO protocol, mod_auth_kerb has the ability to ask the user for a password using basic authentication then validate that password by attempting to authenticate to the KDC. This can be useful if there is a need for the web site to be accessible to its authorised users from machines that are not part of the Kerberos realm, however it is significantly less secure than true Kerberos authentication. Both SPNEGO and password authentication are enabled by default. In this example there is no requirement for the site to be accessible to non-SPNEGO-enabled web browsers, therefore password authentication has been disabled using the KrbMethodK5Passwd directive. For completeness, SPNEGO has been explicitly enabled using the KrbMethodNegotiate directive.

The Krb5Keytab directive specifies the pathname of the keytab to which the HTTP service principal has been added. It should match whatever was passed to the ktadd command of kadmin earlier in this procedure.

Although a <Location> container has been used in this example, it would be equally acceptable for the above directives to be placed within a <Directory>, <Files> or <Proxy> container or within an .htaccess file.

Specify a list of authorised users

Setting the authentication method does not by itself restrict access to the server. This is because Apache defaults to allowing access by anonymous users, and unless that behaviour is overridden then the authentication method (whatever it might be) will not be invoked.

In this example there are only four users who need access, and the simplest way to arrange that is by means of a Require directive:

<Location />
 # ...
 Require user dougal@EXAMPLE.COM brian@EXAMPLE.COM ermintrude@EXAMPLE.COM dylan@EXAMPLE.COM

Note that each name is qualified by the Kerberos realm of which it is a member.

For servers with larger numbers of users this is obviously not a scalable solution, however Apache has other authorisation methods that can efficiently handle large numbers of users including mod_authz_dbd and mod_authnz_ldap.

Reload the Apache configuration

See Cause a system service to reload its configuration. On recent Debian-based systems the required command is:

service apache2 force-reload

Security considerations

Password authentication

As noted above, mod_auth_kerb has the ability to request a username and password from the web browser using HTTP Basic Authentication, then check whether that username and password are valid using Kerberos. This approach has three serious drawbacks compared to true Kerberos authentication:

The first of these points can be addressed by enabling access via TLS (SSL) and disabling plain HTTP. The second and third points are less tractable, and undermine many of the security benefits provided by the Single Sign-on model generally and by Kerberos in particular.

In practice it is sometimes necessary to allow access from hosts that are not part of the Kerberos realm or from user agents that do not support SPNEGO. For this reason it is unrealistic to recommend that password authentication should never be used as a fallback, however it is best avoided if you can and should not be permitted merely because it is enabled by default.


Authentication using SPNEGO addresses the concerns listed above but the manner in which it is integrated with HTTP is far from ideal. When a client authenticates to a Kerberos network service one of the products of the authentication process is an encryption key that the client and server can use to secure any further communication between them. This is not used when an HTTP connection is authenticated using SPNEGO, which means that if a connection is hijacked after authentication has completed then there is nothing to prevent an attacker from issuing unauthorised HTTP commands.

This risk can be greatly reduced by using TLS (SSL) to secure the connection. This prevents a connection from being hijacked once it has been established, and prevents a server from accepting connections to a web site for which it does not have a valid certificate. It is not a perfect solution because of the large number of organisations that can issue certificates. There is a solution which uses channel binding to link the TLS key to Kerberos, however at the time of writing it had not been widely implemented (and is not supported by mod_auth_kerb).

See also

Further reading

Tags: apache | gssapi | kerberos | spnego