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 the version 1.4 and later JREs from all vendors. (JAAS was available as a separately-downloadable optional package starting in version 1.3.) The Kerberos LoginModule required for the JAAS authentication in this tutorial may not be available in all vendors' JREs. We will be using the LoginModule for Kerberos provided in the JRE from Sun Microsystems (versions 1.4 and later).
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 JRE v 1.4 and later.
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 such as that from Microsoft for Windows 2000, which
does not include a krb5.conf
file, you will either
need to create one or use system properties as described in
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.
krb5.conf
Configuration FileThe 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>\lib\security
(Windows)<java-home>/lib/security
(Solaris and
Linux)Here <java-home> refers to the directory where
the JRE was installed. For example, if you have J2SE 5.0 installed
on Solaris in a directory named /j2sdk1.5
, the
directory in which the configuration file is looked for is:
/j2sdk1.5/jre/lib/security
If the file is still not found, then an attempt is made to locate it as follows:
/etc/krb5/krb5.conf
(Solaris)c:\winnt\krb5.ini
(Windows)/etc/krb5.conf
(Linux)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.
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
".
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/EXAMPLE.COM@EXAMPLE.COMIn 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/ENG.EAST.EXAMPLE.COM@SALES.WEST.EXAMPLE.COM krbtgt/SALES.WEST.EXAMPLE.COM@ENG.EAST.EXAMPLE.COMThese principals, known as remote Ticket Granting Server principals, must be created on both realms.
On Windows 2000 KDC, the krbtgt
account is created
automatically when a Windows 2000 domain is created. This account
cannot be deleted and renamed.
When you set up multiple realms, you must decide if your realm configuration will be "hierarchical" (one realm is a superset of the other) or "direct" (the mapping between realms must be defined).
The [capaths]
section in the Kerberos configuration
file defines a series of authentication paths used for transitive
cross-realm authentication. Clients use [capaths]
to
determine the correct path for doing transitive cross-realm
authentication. Application servers check the
[capaths]
section to determine if a cross-realm
authentication path is valid.
For example, to set-up cross realm authentication between
ENG.EAST.EXAMPLE.COM
and
SALES.WEST.EXAMPLE.COM
, krb5.conf
should
include the following entry:
[capaths] ENG.EAST.EXAMPLE.COM = { SALES.WEST.EXAMPLE.COM = . } SALES.WEST.EXAMPLE.COM = { ENG.EAST.EXAMPLE.COM = . }On Windows 2000, you must set up a trust relationship between the two realms. For configuration details, refer to Step-by-Step Guide to Kerberos 5 (krb5 1.0) Interoperability on Microsoft's Web site.