Kerberos / Spnego Configuration

Different web-applications running inside a TIF instance may support single-sign-on via Spnego/Kerberos authentication for users on a Windows or Active Directory based network.

In order to support this, one need to configure the underlying Kerberos/Spnego modules within the JDK with a number of settings.

You should enable SSL for TIF when using Kerberos authentication.

Active Directory Configurations

On your Active Directory server, you need to do some administration and generate a so called "keytab" file.

You need the following information

  • hostname of the machine, which your TIF instance is running from

    • Example: tifserver.exampledomain.com

  • An Active Directory user

    • Example: tifuser

First, you need to run the setspn command (https://technet.microsoft.com/en-us/library/cc731241(v=ws.11).aspx).

setspn -A HTTP/tifserver.exampledomain.com tifuser

Next step is to create/generate the keytab file.

This keytab file should be transferred to the TIF server and kept securely and not readable for the "world".

Creating the keytab is used by the command ktpass. (https://technet.microsoft.com/en-us/library/cc753771(v=ws.11).aspx)

ktpass -out c:\dir\krb5.keytab -princ HTTP/tifserver.exampledomain.com@EXAMPLEDOMAIN.COM -mapUser tifuser -mapOp set -pass THE_SECRET_PASSWORD -crypto AES256-SHA1 -pType KRB5_NT_PRINCIPAL
change the hostname + username/password and also the "-out" argument above to match your environment.

Also note that you need to review what encryption algorithm to be used. Over time, this may change and different versions of Windows may add new algorithms, which we are not able to keep up-to-date in this document.

TIF Properties

Within the file ${TIF_ROOT}/etc/tif.custom.properties you will have some property keys to set. These keys corresponds to Java System properties, and you can if wanted use the Java system property and specify them via "-D" parameters on the command line. However, that requires modifying the start scripts for TIF so the recommended approach is to apply these within the tif.custom.properties file.

Required properties:

TIF Property Key Java System Property Description

kerberos.enabled

-

A boolean flag indicating if to enable kerberos via TIF property key/values.

You can still configure Kerberos via Java system parameters as usual, however, you need to set this property to true in order to let TIF configure the kerberos module through properties specified in here.

kerberos.conf

java.security.krb5.conf

Points out the file configuring the underlying kerberos setup.

kerberos.authLoginConfig

java.security.auth.login.config

Configures Spnego vs Kerberos

kerberos.authUseSubjectCredsOnly

javax.security.auth.useSubjectCredsOnly

This one is by default set to FALSE and should be in this case.

kerberos.debug

sun.security.spnego.debug

Used to enable debugging from the JDK layer. Default is false.

Should only be used for debugging during setup, otherwise your log-files will be filled quite fast.
If a Java system property already has been defined, TIF will never re-assign that value.

Example Configurations

Below is a working example how to setup all. Note that we have tested with a Windows 2008 server setup, other versions may need other configuration values or switches/arguments to setspn/ktpass.

${tif.home}/etc/tif.custom.properties
kerberos.enabled=true (1)
kerberos.conf=${tif.home}/etc/kerberos/krb5.ini (2)
kerberos.authLoginConfig=${tif.home}/etc/kerberos/spnego.conf (3)
1 Required to enable setting up kerberos via TIF properties
2 Points out a kerberos configuration file
3 Points out a Spnego configuration file
${tif.home}/etc/kerberos/krb5.ini
[libdefaults]
default_realm = EXAMPLEDOMAIN.COM
default_keytab_name = FILE:c:/apps/tif-server/etc/spnego/krb5.keytab
permitted_enctypes = aes128-cts aes256-cts arcfour-hmac-md5
default_tgs_enctypes = aes128-cts aes256-cts arcfour-hmac-md5
default_tkt_enctypes = aes128-cts aes256-cts arcfour-hmac-md5

[realms]
EXAMPLEDOMAIN.COM= {
    kdc = 192.168.0.123
    admin_server = 192.168.0.123
    default_domain = EXAMPLEDOMAIN.COM
}

[domain_realm]
exampledomain.com= EXAMPLEDOMAIN.COM
.exampledomain.com = EXAMPLEDOMAIN.COM

[appdefaults]
autologin = true
forwardable = true
${tif.home}/etc/kerberos/spnego.conf
com.sun.security.jgss.initiate {
     com.sun.security.auth.module.Krb5LoginModule required
     principal="HTTP/tifserver.exampledomain.com@EXAMPLEDOMAIN.COM"
     useKeyTab=true
     keyTab="c:/apps/tif-server/etc/spnego/krb5.keytab"
     storeKey=true
     isInitiator=false;
};

com.sun.security.jgss.accept {
     com.sun.security.auth.module.Krb5LoginModule required
     principal="HTTP/tifserver.exampledomain.com@EXAMPLEDOMAIN.COM"
     useKeyTab=true
     keyTab="c:/apps/tif-server/etc/spnego/krb5.keytab"
     storeKey=true
     isInitiator=false;
};

Please read more from the link below regarding additional properties:

https://docs.oracle.com/javase/8/docs/jre/api/security/jaas/spec/com/sun/security/auth/module/Krb5LoginModule.html

Tips

Setting up kerberos/spnego is a "fragile" task and its easy to do something wrong. The debugging information you will see from the JDK level is far from helpful in some cases.

Below are some URLs with information that might help:

A last recommendation is to NOT test the setup with the client and server on the same machine!

Also note that the site/host running your TIF instance may need to be added to the "Trusted Sites" on the clients. This is typically updated via GPO in Windows, done by the Domain Administrators.