Fork me on GitHub

This page provides you with a detailed view on how to implement SSO with Apache on Linux. We use Ubuntu as distribution but you should be able to adapt the file paths to your needs.

Prepare webserver environment

For a working SSO configuration, you need to install Kerberos client libraries on the web server.

sudo apt-get install krb5-user

You have to add your Active Directory Kerberos realm to /etc/krb5.conf:

[libdefaults]
default_realm = TEST.AD
# ...
		 
[realms]
TEST.AD = {
	# kdc and admin_server are DNS entries pointing to your primary domain controller
	kdc = dc1.test.ad
	admin_server = dc1.test.ad
}
[domain_realm]
# Please note the leading dot and the upper-case
.test.ad = TEST.AD
test.ad = TEST.AD
		

Please note that the upper-case format for default_realm and domain_realm is important.

Synchronize clocks

Kerberos requires a synchronized time between all belonging parties. The best fit is to use NTP. If you domain controller provides NTP, your webserver can use it as reference:

sudo apt-get install ntpdate
sudo ntpdate dc1.test.ad

Please note that ntpdate is deprecated and is only used for testing. Consult your distribution documentation how to set up NTP properly.

Prepare Active Directory

Add dedicated Kerberos user

You should create a new Active Directory user which is dedicated for Kerberos usage. For further reference, the username of this user $KERBEROS_USER and his password is $KERBEROS_PASSWORD.

Create keytab file

On the domain controller you have to create a .keytab file:

ktpass -princ HTTP/webserver.test.ad@TEST.AD -mapuser $KERBEROS_USERNAME@TEST.AD -pass $KERBEROS_PASSWOR -crypto RC4-HMAC-NT -ptype KRB5_NT_PRINCIPAL -out C:\Temp\kerberos.keytab

Some notes about this:

  • If you use HTTPS, which we highly recommend, you must use HTTPS/webserver.test.ad as principal.
  • Kerberos authentication is only used when you access http://webserver.test.ad and not http://$IP_OF_WEBSERVER.
  • To prevent further work and problems, the webserver should be directly accessible and not through a proxy.

Copy the kerberos.keytab file to the webserver's path /etc/kerberos.keytab and change the ownership to this file to the Apache user.

After everything has been configured you can retrieve a valid Kerberos token on the webserver by using

kinit -p Administrator@TEST.AD

Enable Kerberos in Apache

There are two different modules available which provide Kerberos functionality: mod_auth_kerb and mod_auth_gssapi. Even if mod_auth_kerb is much older, please go with it. mod_auth_kerb prints out log messages which you can use for debugging. mod_auth_gssapi does not provide enough useful information during debugging.

To enable Kerberos in your Apache configuration you have to install the module by using apt-get or dnf. After that, open /etc/apache2/sites-available/000-default.conf or any other vhost configuration file you want to use

 <VirtualHost *:80>
 
	# ...
	ServerName webserver.test.ad      
	<Location />
		AuthType Kerberos
		AuthName "Kerberos authenticated intranet"
		KrbAuthRealms TEST.AD
		KrbServiceName HTTP/webserver.test.ad
		Krb5Keytab /etc/kerberos.keytab
		KrbMethodNegotiate On
		KrbMethodK5Passwd On
		require valid-user
	</Location>
</VirtualHost>

Configure browsers

You have to configure the browsers you are using.

Debugging

Apache

With

LogLevel trace8

in your Apache configuration you enable a high log level to debug the Kerberos authentication process.

Client credentials

You can use

# Linux
kdestory -A
# Windows 
klist purge

to reset any Kerberos token on your local machine.