Kerberos Requirements

Kerberos Version 5 is used for both the authentication and secure communication aspects of the client and server applications developed in this tutorial. The reader is assumed to already be familiar with Kerberos. See the Kerberos reference documentation.

The JAAS framework, and the Kerberos mechanism required by the Java GSS-API methods, are built into JDKs from all vendors. The Kerberos LoginModule required for the JAAS authentication in this tutorial may not be available in all vendors' JDKs. We will be using the LoginModule for Kerberos provided by Oracle's JDK.

In order to run the sample programs, you will need access to a Kerberos installation. As described in the following sections, you may also need a krb5.conf Kerberos configuration file and an indication as to where that file is located.

As with all Kerberos installations, a Kerberos Key Distribution Center (KDC) is required. It needs to contain the user name and password you will use to be authenticated to Kerberos.

Note:

A KDC implementation is part of a Kerberos installation and not a part of the JDK.

As with most Kerberos installations, a Kerberos configuration file krb5.conf is consulted to determine such things as the default realm and KDC. If you are using a Kerberos implementation that does not include a krb5.conf file (such as one from Windows), you will either need to create one or use system properties as described in Setting Properties to Indicate the Default Realm and KDC.

Setting Properties to Indicate the Default Realm and KDC

Typically, the default realm and the KDC for that realm are indicated in the Kerberos krb5.conf configuration file. However, if you like, you can instead specify these values by setting the following system properties to indicate the realm and KDC, respectively:

java.security.krb5.realm
java.security.krb5.kdc

If you set one of these properties you must set them both.

Also note that if you set these properties, then no cross-realm authentication is possible unless a krb5.conf file is also provided from which the additional information required for cross-realm authentication may be obtained.

If you set values for these properties, then they override the default realm and KDC values specified in krb5.conf (if such a file is found). The krb5.conf file is still consulted if values for items other than the default realm and KDC are needed. If no krb5.conf file is found, then the default values used for these items are implementation-specific.

Locating the krb5.conf Configuration File

The essential Kerberos configuration information is the default realm and the default KDC. As shown in Setting Properties to Indicate the Default Realm and KDC, if you set properties to indicate these values, they are not obtained from a krb5.conf configuration file.

If these properties do not have values set, or if other Kerberos configuration information is needed, an attempt is made to find the required information in a krb5.conf file. The algorithm to locate the krb5.conf file is the following:

• If the system property java.security.krb5.conf is set, its value is assumed to specify the path and file name.

• If that system property value is not set, then the configuration file is looked for in the directory

  • <java-home>\conf\security (Windows)
  • <java-home>/conf/security (Linux, and macOS)

  Here <java-home> refers to the directory where the JDK is installed.

• If the file is still not found, then an attempt is made to locate it as follows:

  • C:\Windows\krb5.ini (Windows)
  • /etc/krb5.conf (Linux)
  • ~/Library/Preferences/edu.mit.Kerberos, /Library/Preferences/edu.mit.Kerberos, or /etc/krb5.conf (macOS)

• If the file is still not found, and the configuration information being searched for is not the default realm and KDC, then implementation-specific defaults are used. If, on the other hand, the configuration information being searched for is the default realm and KDC because they weren't specified in system properties, and the krb5.conf file is not found either, then an exception is thrown.

• On Windows, if a krb5.conf file cannot be found or it does not contain settings for the default realm and its KDC, then the environment variables USERDNSDOMAIN and LOGONSERVER are used as the default realm and its KDC.

Naming Conventions for Realm Names and Hostnames

By convention, all Kerberos realm names are uppercase and all DNS hostname and domain names are lowercase. On Windows, domains are also Kerberos realms; however, the realm name is always the uppercase version of the domain name.

Hostnames are case insensitive and by convention they are all lowercase. They must resolve to the same hostname on the client and server by their respective naming services.

However, in the Kerberos database hostnames are case sensitive. In all host-based Kerberos service principals in the KDC, hostnames are case-sensitive. The hostnames used in the Kerberos service principal names must exactly match the hostnames returned by the naming service. For example, if the naming service returns a fully qualified lowercased DNS hostname, such as raven.example.com, then the administrator must use the same fully qualified lowercased DNS hostname when creating host-based principal names in the KDC: host/raven.example.com.

Cross-Realm Authentication

In cross-realm authentication, a principal in one realm can authenticate to principals in another realm.

In Kerberos, cross-realm authentication is implemented by sharing an encryption key between two realms. The KDCs in two different realms share a special cross-realm secret; this secret is used to prove identity when crossing the boundary between realms.

The key that is shared is the Ticket Granting Service principal's key. Here's a typical Ticket Granting Service principal for a single realm:

ktbtgt/[e-mail]

In cross realm authentication, two principals are created on each participating realm. For two realms, ENG.EAST.EXAMPLE.COM and SALES.WEST.EXAMPLE.COM, these principals would be:

krbtgt/[e-mail]
krbtgt/[e-mail]

These principals, known as remote Ticket Granting Server principals, must be created on both realms.

For a Windows KDC, the krbtgt account is created automatically when a Windows domain is created. This account cannot be deleted and renamed.