Kerberos

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 = <SUB-DOMAIN>.<DOMAIN>.<TLD>
[realms]
  <SUB-DOMAIN>.<DOMAIN>.<TLD> = {
     # kdc and admin_server are DNS entries pointing to your primary domain controller
     kdc = <sub-domain>.<domain>.<tld>
     admin_server = <sub-domain>.<domain>.<tld>
  }

[domain_realm]
  # Please note the leading dot and the upper-case
  .<sub-domain>.<domain>.<tld> = <SUB-DOMAIN>.<DOMAIN>.<TLD>
  <sub-domain>.<domain>.<tld> = <SUB-DOMAIN>.<DOMAIN>.<TLD>

Note

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 <your-ntp-host>

Note

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. Please use the OLD Crypto Syntax:

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

Old Crypto:

ktpass -princ HTTP/SERVER.<sub-domain>.<domain>.<tld>@<SUB-DOMAIN>.<DOMAIN>.<TLD> -mapuser username@<SUB-DOMAIN>.<DOMAIN>.<TLD> -ptype KRB5_NT_PRINCIPAL -mapop set -pass NEWPASSWORD -out c:\krb5.keytab

New Crypto:

ktpass -princ HTTP/server.<sub-domain>.<domain>.<tld>@<SUB-DOMAIN>.<DOMAIN>.<TLD> -mapuser username@<SUB-DOMAIN>.<DOMAIN>.<TLD> -ptype KRB5_NT_PRINCIPAL -crypto AES256-SHA1 -pass password -out c:\krb5.keytab

Some notes about this:

${ENCRYPTION_TYPE} can be one of AES256-SHA1, AES128-SHA1, RC4-HMAC-NT, DES-CBC-CRC or DES-CBC-MD5. You should be good to go with AES256-SHA1 but this depends upon your environment. Please note that the Kerberos principal you are using is case-sensitive. If your keytab entry does not match, please check for differences in upper/lower-case writing. If you use HTTPS, which we highly recommend, you must use HTTP/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 that, you have to change the Permission for the new Keytab file:

chown -v www-data:root /etc/*.keytab && chmod -v 440 /etc/*.keytab

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/Install the Apache Module

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.

For Ubuntu 18.x use:

apt -y install libapache2-mod-auth-kerb

Edit apache2.conf and add:

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

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 SERVER_NAME.<sub-domain>.<domain>.<tld>
     <Location />
         AuthType Kerberos
         AuthName "SSO Authentifizierung"
         KrbAuthRealms <SUB-DOMAIN>.<DOMAIN>.<TLD>
         KrbServiceName HTTP/SERVER_NAME.<sub-domain>.<domain>.<tld>
         Krb5Keytab /etc/kerberos.keytab
         KrbLocalUserMapping on
         KrbMethodK5Passwd on
         KrbAuthoritative on
         KrbVerifyKDC off
         require valid-user
     </Location>
 </VirtualHost>

neustarten des Apache Dienstes:

systemctl restart apache2

Configure browsers

Using Kerberos implies that your client’s browser must be configured properly!

Depending upon which browser your clients use, you have to set up the Kerberos configuration in a different way. Please note that without a proper configured browser, the Kerberos token is not sent to the server and so SSO will not work!

Internet Explorer

The URL http://webserver.test.ad must be added to Internet options > Security > Local intranet.

You can deploy this setting by using a group policy for the node Computer Configuration/Policies/Administrative Templates/Windows Components/Internet Explorer/Internet Control Panel/Security Page/Site to Zone Assignment List.

Each of your SSO-enabled sites has to be in the Intranet zone (value = 1). You can use wildcards like “https://*.test.ad”.

Benutzerkonfiguration -> Administrative Vorlage -> Windows-Komponenten -> Internet Explorer -> Internetsystemsteuerung -> Sicherheitsseite -> Liste der Site zu Zonenzuweisungen

Please note, that enforcing a GPO for Site to Zone Assignment List does no longer allow your users to edit the setting on their own! There are two options:

Collect each custom configuration and assemble the complete list. In most cases you can use a wildcard on your internal domain like https://.test.ad* and http://.test.ad* to include all internal sites. Configure a custom assignment list by using a logon script or something like OpsCode Chef or Microsoft’s Desired State Configuration. The first option should be the way to go.

Check the other security settings Please make sure that there your SSO-enabled domain is only entered in the Local intranet zone and nowhere else! If you have falsely entered the same domain in Trusted sites and Local intranet, the first one is used an no Kerberos token is sent by Internet Explorer to the webserver.

Chrome

In order to use Chrome for SSO you also must deploy the settings shown in the Internet Explorer configuration above.

Newer versions of Chrome do automatically detect the Kerberos negotiation and transmit your token. In case you are using an outdated version of Chrome we highly suggest to update it for security reasons.

If an update is not possible at all, Chrome must be started with the parameter

–auth-server-whitelist=”*.test.ad”

like:

C:Program Files (x86)GoogleChromeApplicationchrome.exe –auth-server-whitelist=”*.test.ad

This setting can be automatically deployed by using group policies.

Download the official group policies for Chrome Follow the installation procedure and open the chrome.admx Configure a policy for the option AuthServerWhitelist Deploy the policy

Firefox

In Firefox you have to go to the about:config page and set the parameters

network.negotiate-auth.trusted-uris network.automatic-ntlm-auth.trusted-uris to http://webserver.test.ad.

The deployment of these settings can be done by using GPO for Firefox. This is a plug-in for Firefox which itself has to be automatically deployed and/or bundled with your NETLOGON script.

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

kdestroy -A

Windows

klist purge

to reset any Kerberos token on your local machine.

Bekannte Fehler

[Tue Jul 19 16:28:24.073702 2022] [auth_kerb:error] [pid 2422434] [client <ip-address>:54039] gss_acquire_cred() failed: Unspecified GSS failure.  Minor code may provide more information (, No key table entry found matching HTTP/<server-name>@), referer: http://<server>.<sub-domain>.<domain>.<tld>/

Hier fehlt der Reverse DNS Eintrag. Der wird mit dem SPN überprüft.

Falsche Antwort:

root@<server-name>:/etc# nslookup <ip-address>
<ip-address>.in-addr.arpa      name = <server-name>.
<ip-address>.in-addr.arpa      name = <server-name>.local.

Richtige Antwort:

root@<server-name>:/etc# nslookup <ip-address>
<ip-address>.in-addr.arpa      name = <server-name>.<sub-domain>.<domain>.<tld>.