ELM client configuration for Kerberos/SPNEGO SSO

Edit online

All IBM® Engineering Lifecycle Management (ELM) clients that are based on Java technology and support Kerberos/SPNEGO authentication must be explicitly configured.

Because the Engineering Workflow Management client for Microsoft Visual Studio IDE, Engineering Workflow Management Windows Explorer integration, and Engineering Workflow Management 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. Engineering Workflow Management Eclipse and Engineering Workflow Management .NET clients (Engineering Workflow Management client for Microsoft Visual Studio IDE, Engineering Workflow Management Windows Explorer integration, and Engineering Workflow Management 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. For Engineering Workflow Management 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.

Kerberos/SPNEGO authentication in ELM 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 ELM 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 ELM clients can be configured for Kerberos/SPNEGO authentication by using Java system properties.

Alternatively, the Engineering Workflow Management 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.

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.
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.

If none of the three system properties are set, the JRE applies the following algorithm.

The JRE searches for the krb5.conf file in the following directory:
Java-Install-Dir\lib\security

Java-Install-Dir/lib/security

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

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
	C:\Windows\krb5.ini
	/etc/krb5.conf
Other systems	/etc/krb5/krb5.conf
	/etc/krb5.conf
	/etc/krb5/krb5.conf
	/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.