CLM client configuration for Kerberos/SPNEGO SSO

All Rational® solution for Collaborative Lifecycle Management (CLM) clients that are based on Java technology and support Kerberos/SPNEGO authentication must be explicitly configured.
Because the Rational Team Concert® Client for Microsoft Visual Studio IDE, Rational Team Concert Windows Explorer integration, and Rational Team Concert MS-SCCI Provider all include an embedded Java component, these clients must be configured for Kerberos authentication as well.
Important: If AES-256 encryption is required, you must replace the policy JAR files (local_policy.jar and US_export_policy.jar) for your JRE. Rational Team Concert Eclipse and Rational Team Concert .NET clients (Rational Team Concert Client for Microsoft Visual Studio IDE, Rational Team Concert Windows Explorer integration, and Rational Team Concert MS-SCCI Provider) include their own version of the IBM® JRE that must be updated as well. For .Net clients, replace the JAR files in the Client_Install_Dir\3rd Party\jre\lib\security directory on the Microsoft .NET client computers with the downloaded files with the same name, where RTC_.NET_Client_Install_Dir is the installation directory for the Microsoft .NET clients. For Rational Team Concert Eclipse, replace the policy JAR files under Client_Install_Dir\jdk\jre\lib\security.

In addition, to support earlier client versions, IBM WebSphere® Application Server must be configured with a special SPNEGO filter. For more information, see Configuring a SPNEGO filter in WebSphere Application Server for compatibility with earlier client versions.

Kerberos/SPNEGO authentication in CLM clients is implemented by using the Generic Security Services Security Application Programming Interface (GSS-API) in the underlying Java Runtime Engine (JRE). This library configuration is controlled with standard system properties from the Java Authentication and Authorization Service (JAAS) or JAAS API (see Table 1).
Table 1. System properties for CLM clients that support Kerberos/SPNEGO
Java system property Description
-Djava.security.krb5.realm Realm (Kerberos domain name) to connect the client to.
Important: The java.security.krb5.realm and java.security.krb5.kdc system properties must be set together; otherwise, they are ignored.
-Djava.security.krb5.kdc Host name of the Microsoft Active Directory Key Distribution Center (KDC) to connect the client to. If the server does not use the default port, the port number must be included as well.
Important: The java.security.krb5.realm and java.security.krb5.kdc system properties must be set together; otherwise, they are ignored.
-Djava.security.krb5.conf Path to a Kerberos Version 5 configuration file.

Although this file has the same format as a krb5.ini or krb5.conf file that might be found in the default location, it is a separate file. The file can have any name, including krb5.conf, and can include other configuration properties. However, only a small subset of configuration properties is needed to have a functional client. Also, the IBM JRE does not support all the configuration properties.

Note: This system property can be set instead of the java.security.krb5.realm and java.security.krb5.kdc properties.

All CLM clients can be configured for Kerberos/SPNEGO authentication by using Java system properties.

Alternatively, the Rational Team Concert Eclipse clients have a configuration interface to set these system properties in their respective connection wizards.

The JRE can also retrieve a configuration file with a well-known name that is in either the operating system directory or the JRE installation directory (see Table 2). JRE installations with Kerberos/SPNEGO frequently rely on these centralized configuration files instead of using system properties.

Administrators can choose a strategy for configuring the client configuration values based on whether they can easily alter the client software deployment or client operating system.

JRE search algorithm for locating the client configuration properties

The JRE applies the following search algorithm to locate the client configuration properties.

  1. If the java.security.krb5.realm and java.security.krb5.kdc system properties are set in the client, the JRE uses these values as the default realm and KDC, respectively.
    Note: These configuration values override any default values that are set in a krb5.conf or krb5.ini file if such a configuration file either is specified in the java.security.krb5.conf system property or is found in one of the default locations.
  2. If the java.security.krb5.realm and java.security.krb5.kdc properties are not set, the JRE looks for the default realm and KDC in a krb5.conf or krb5.ini file if such a file either is specified in the java.security.krb5.conf property or is found in one of the default locations.
  3. If none of the three system properties are set, the JRE applies the following algorithm.
    1. The JRE searches for the krb5.conf file in the following directory:

      Windows operating system icon Java-Install-Dir\lib\security

      UNIX operating system icon Java-Install-Dir/lib/security

      where Java-Install-Dir is the directory where the JRE is installed on the client computer.

    2. If a krb5.conf file still is not found, the JRE searches for a configuration file in the location that is specified in Table 2.
      Table 2. Possible location of the Kerberos configuration file on the client computer
      Operating system Location
      Windows operating system icon C:\Windows\krb5.ini
      Linux operating system icon /etc/krb5.conf
      Other UNIX operating system icon systems /etc/krb5/krb5.conf
      Mac OS X operating system icon /etc/krb5.conf
      z/OS operating system icon /etc/krb5/krb5.conf
      IBM i operating system icon /QIBM/UserData/OS400/NetworkAuthentication/krb5.conf

Example krb5.conf or krb5.ini file

The following example krb5.conf or krb5.ini file includes a minimal configuration. Advanced setups might require additional parameters.
    [libdefaults]
        default_realm = REALM.NAME
    [realms]
        REALM.NAME = {
            kdc = ad.my.domain:88
            default_domain = my.domain
        }
    [domain_realms]
        .my.domain = REALM.NAME
The example includes these parameters:
  • REALM.NAME is the Kerberos realm.
  • my.domain is the domain name.
  • ad.my.domain is the KDC host name.
Important:
  • The definitions in this file are case-sensitive. For example, the Kerberos realm (REALM.NAME in the example) must be in all uppercase letters.
  • The Kerberos krb5.conf or krb5.ini file described here is not identical to the Kerberos configuration file with the same name that is used to configure IBM WebSphere Application Server with SPNEGO. While both files support Kerberos in the JRE, they have different purposes.

video icon Video

Jazz.net channel
Software Education channel

learn icon Courses

IoT Academy
Skills Gateway

ask icon Community

Jazz.net
Jazz.net forums
Jazz.net library

support icon Support

IBM Support Community
Deployment wiki