Networking Single Sign On Kerberos SSO with Apache on Linux

This page provides you with a detailed view on how to implement SSO with Apache on Linux by using the Kerberos protocol. Kerberos SSO can be enabled in Apache with mod_auth_kerb and mod_auth_gssapi.

#Prepare webserver environment

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

sudo apt-get install krb5-user

Add your Active Directory’s 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

#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_PASSWORD} -crypto ${ENCRYPTION_TYPE} -ptype KRB5_NT_PRINCIPAL -out C:\Temp\kerberos.keytab

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. mod_auth_kerb is much older, but has more detailled log messages you can use for debugging

#Kerberos SSO with mod_auth_gssapi

To enable mod_auth_gssapi in your Apache configuration you have to install the module by using apt-get or dnf, e.g:

# on Debian-based distributions:
sudo apt-get install libapache2-mod-auth-gssapi
# on RHEL-based distrubtions:
sudo dnf install mod_auth_gssapi 

sudo a2enmod auth_kerb

After installing the module, open your Apache’s configuration file (e.g. /etc/apache2/sites-available/000-default.conf) and paste in the following configuration snippet:

<VirtualHost *:80>
	# ...
	<Location />
		AuthType GSSAPI
		AuthName "Kerberos authenticated intranet with mod_auht_gssapi"

		GssapiCredStore keytab:/etc/kerberos.keytab

		# Only allow krb5 and ignore ntlmssp and iakerb
		GssapiAllowedMech krb5

		# We don't want to fallback to Basic Auth
		GssapiBasicAuth Off

		# Resolve remote's user into REMOTE_USER variable. Proper setting of [realms].auth_to_local in /etc/krb5.conf is required
		GssapiLocalName On

		# Enforce encrypted HTTPS/TLS connection
		GssapiSSLonly On

		require valid-user
	</Location>
</VirtualHost>

#Kerberos SSO with mod_auth_kerb

To enable mod_auth_kerb in your Apache configuration you have to install the module by using apt-get or dnf, e.g:

# on Debian-based distributions:
sudo apt-get install libapache2-mod-auth-kerb
# on RHEL-based distrubtions:
sudo dnf install mod_auth_kerb

sudo a2enmod auth_kerb

After installing the module, open your Apache’s configuration file (e.g. /etc/apache2/sites-available/000-default.conf) and paste in the following configuration snippet:

 <VirtualHost *:80>
 
	# ...
	ServerName webserver.test.ad      
	<Location />
		AuthType Kerberos
		AuthName "Kerberos authenticated intranet with mod_auth_kerb"

		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

You can raise the log levels in your Apache configuration to debug Kerberos’ authentication process:

# Available loglevels: trace8, ..., trace1, debug, info, notice, warn, error, crit, alert, emerg.
# It is also possible to configure the loglevel for particular
# modules, e.g.
# LogLevel trace8 ssl:warn

LogLevel info auth_kerb:debug ssl:warn

#Client credentials

You can use

# Linux
kdestroy -A
# Windows 
klist purge

to reset any Kerberos token on your local machine.