Engineering Lifecycle Management client configuration for Kerberos/SPNEGO SSO

Establishing a connection with the Kerberos/SPNEGO enabled Engineering Lifecycle Management Server

1. Set Java system properties.

   You can configure Engineering Lifecycle Management clients for Kerberos/SPNEGO authentication by using Java system properties java.security.krb5.realm and java.security.krb5.kdc or java.security.krb5.conf. They can be set by modifying the client configuration file or by using the client connection wizard.

   • Setting system properties by using connection wizard

     The Engineering Workflow Management Eclipse clients have a configuration interface to set these system properties in their respective connection wizards.

     

     Connection wizard can also make use Kerberos Configuration file. See below for Kerberos configuration file sample.

   • Setting system properties by using client configuration file
     These Java System properties can be set in the Engineering Lifecycle Management Client configuration file under the - vmargs section. For example for configuring SCM client, the configuration file Client- Install-Dir\scmtools\eclipse\scm.ini can be used. When configured it looks like below:

     -vm
     ../../jdk/jre/bin
     -startup
     plugins/org.eclipse.equinox.launcher_1.3.0.v20140415-2008.jar
     --launcher.library
     plugins/org.eclipse.equinox.launcher.win32.win32.x86_64_1.1.200.v20150204-1316
     --launcher.suppressErrors
     -data
     @noDefault
     -vmargs
     -Xmx512m
     -Xshareclasses:nonfatal
     -Xquickstart
     -Dosgi.requiredJavaVersion=1.8
     -Xdump:system:events=systhrow,filter=java/lang/OutOfMemoryError,request=exclusive+prepwalk
     -Dorg.eclipse.emf.ecore.plugin.EcorePlugin.doNotLoadResourcesPlugin=true
     -Djava.security.krb5.realm=REALM.NAME
     -Djava.security.krb5.kdc=ad.my.domain

     The previous example includes the following parameters:

     • REALM.NAME is the Kerberos realm
     • ad.my.domain is the KDC hostname
     Locations of some of the client configuration files are as following:

     • Build-Client-Install-Dir\buildsystem\buildengine\eclipse\jbe.ini
     • SCM-Client-Install-Dir\scmtools\eclipse\scm.ini
     • EWM-Client-Install-Dir\eclipse.ini
2. Initiate the connection by selecting the authentication type as Kerberos/SPNEGO

   The authentication type can be selected in the connection wizard or by providing appropriate parameter value on the command line.

   Below is a sample command line that uses Kerberos authentication type for scm client:

   scm login -r https://jazzserver1.realm.name:9443/ccm --kerberos

   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:

      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.

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

    [libdefaults]
        default_realm = REALM.NAME
    [realms]
        REALM.NAME = {
            kdc = ad.my.domain:88
            default_domain = my.domain
        }
    [domain_realms]
        .my.domain = REALM.NAME

Providing a session key to the IBM JRE to enable Kerberos/SPNEGO SSO in Engineering Lifecycle Management Eclipse client

By default, Microsoft Windows restricts third-party applications from retrieving ticket-granting ticket (TGT) and session key pairs from the Kerberos security package. The IBM JRE that is included in Engineering Lifecycle Management Eclipse clients is one such third-party application that is affected by this Windows restriction. Engineering Lifecycle Management web clients are not affected. If Eclipse client is installed without selecting Integrated Windows Authentication, you must update the Windows registry manually to remove this restriction.

1. Open the Windows registry editor, regedit.
2. Navigate to HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Lsa\Kerberos\Parameters.
3. Create the allowtgtsessionkey key with the following attributes and values:
   • Data type: REG_DWORD
   • Value: 1 (default is 0)
   Note: For some versions of Windows, the allowtgtsessionkey key must be created in HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Lsa\Kerberos. To avoid issues, it is best to create the key in both locations.
4. Restart the client computer.