Configure Apache to use Kerberos authentication
|Debian (Lenny, Squeeze)|
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
dylan. The realm can be administered using the principal
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:
- Install the
- Create a service principal for the web server.
- Create a keytab for the service principal.
- Specify the authentication method to be used.
- Specify a list of authorised users.
- 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:
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
apt-get install libapache2-mod-auth-kerb
and on Red Hat-based systems by the package
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).
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
If you are using MIT Kerberos then the service principal can be created using the
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.
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
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
kadmin -p bofh/admin -q "ktadd -k /etc/httpd/http.keytab HTTP/www.example.com" chown apache /etc/httpd/http.keytab
-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
kinit -k -t /etc/apache2/http.keytab HTTP/www.example.com klist
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 </Location>
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
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.
<Location> container has been used in this example, it would be equally acceptable for the above directives to be placed within a
<Proxy> container or within an
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
<Location /> # ... Require user dougal@EXAMPLE.COM brian@EXAMPLE.COM ermintrude@EXAMPLE.COM dylan@EXAMPLE.COM </Location>
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
See Cause a system service to reload its configuration. On recent Debian-based systems the required command is:
service apache2 force-reload
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 password is sent unencrypted as part of the HTTP stream.
- The password is exposed to the Apache server.
- The password must be entered mid-session.
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
- Create a service principal using MIT Kerberos
- Add a host or service principal to a keytab using MIT Kerberos
- Configure Firefox to authenticate using SPNEGO and Kerberos
- Configure Chromium to authenticate using SPNEGO and Kerberos
Kerberos Module for Apache (
mod_auth_kerbofficial home page)