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 you need to install Kerberos on the webserver

sudo apt-get install krb5-kdc krb5-admin-server

The file /etc/krb5.conf has to be modified to add your Active Directory Kerberos realm:

[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.

After the configuration has been saved, the Kerberos service must be restarted

sudo service krb5-kdc restart
sudo service krb5-admin-server restart

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.

Creating a Kerberos database

To speed up the generation of the Kerberos database by providing enough entropy, you can use haveged

sudo apt-get install haveged
haveged defaults

The database can be then generated by using

sudo kdb5_util create -s test.ad

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

Kerberos must be enabled in your Apache configuration. 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>

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.