Configuring JDBC clients for Kerberos client authentication

The general procedure for configuring client connections when Kerberos Client Authentication is enabled for DB2/Db2 Big SQL is outlined in detail in the following IBM developerWorks article: Connect your apps to DB2 with high-security Kerberos

Briefly, the procedure is as follows:

1. If the client machine is external to the cluster you will need to point the client side at the same domain realm. If the client is a Linux machine then configure an /etc/krb5.conf to be consistent with the same file on the Db2 Big SQL server side, or if the client is a Windows machine then use the equivalent C:\windows\krb5.ini configuration file.
2. Configure the JRE to use a custom JAAS configuration file.
   Note:

   1. It may not be desirable to change the java.security file as this is in effect a global configuration file that could affect other applications or services using the associated JRE. An alternative is to specify the JAAS configuration file using the java.security.auth.login.config property when launching the java application. For example, when starting an application myJavaApp, a custom JAAS configuration file .myjaas.conf can be specified as follows:

      java myJavaApp -Djava.security.auth.login.config=/home/user1/.myjaas.conf

      This approach ensures that there is no side affects to other applications that happen to use the same JRE.
   2. Step 2 and Step 3 are not required if a cached ticket granting ticket (TGT) is used (see Step 6.b below). This option may be preferable as it does not require modification of the jre/lib/security/java.security file.

   Both the IBM JRE and SUN (OpenJDK/OracleJDK) JREs are supported. The steps are almost the same in both cases:

   1. Determine which Java Runtime Environment (JRE) your client is using.
   2. Locate the java.security file for this JRE. This file will reside under the lib/security directory of the JRE, for example:

      ./jre/lib/security/java.security

   3. Open the java.security file for editing, uncomment the following line in this file to point to a custom JAAS configuration file (as described in step 3 below), and save the file:

      #login.config.url.1=file:${user.home}/.java.login.config

   4. Confirm that the list of security provider entries contains JCE and GSS providers, for example:
      If SUN Java is used, make sure the following entries are present:

      security.provider.1=com.sun.crypto.provider.SunJCE
      security.provider.2=sun.security.jgss.SunProvider

      If IBM Java is used, make sure the following entries are present:

      security.provider.1=com.ibm.crypto.provider.IBMJCE
      security.provider.2=com.ibm.security.jgss.IBMJGSSProvider

3. A JAAS configuration file needs to be created at the location specified in the java.security file in Step 2. The JAAS configuration file is required by the JDBC client to connect to Db2 Big SQL. Create the following file named .java.login.config on the head node and on any other machines and user home directories on which you are running JDBC client connections:

   JaasClient{
        com.sun.security.auth.module.Krb5LoginModule optional
        useDefaultCcache=false;
   };

   Note:

   1. To enable debugging messages for the JDBC connection, add a property debug = true in the JAAS configuration file.
   2. If the Java environment is the IBM JRE, then replace sun with ibm in the loginModule.
4. Optional: Apply the unrestricted Java Cryptography Extension (JCE)
   By default, the Java Cryptography Extension (JCE) is shipped with restricted or limited strength ciphers. To use 192-bit and 256-bit Advanced Encryption Standard (AES) encryption algorithms, you can apply unlimited jurisdiction policy files. The following are the steps required to do this:

   1. Download the unlimited policy file JARs. For the IBM SDK for Java, these files are available at the following location: https://www14.software.ibm.com/webapp/iwm/web/preLogin.do?source=jcesdk
   2. In the ./jre/lib/security subdirectories of the JRE path, replace the existing two JCE policy JARs (US_export_policy.jar and local_policy.jar) with these newly downloaded JAR files.
   3. From the Ambari UI, restart the Db2 Big SQL service.
5. Authenticate with Kerberos.
   The procedure is as follows:

   1. When connecting to Db2 Big SQL with Kerberos Client Authentication enabled, the securityMechanism=11 property passed via the JDBC client telling the JCC driver that a Kerberos connection is required to be made with Db2 Big SQL.
   2. Once the securityMechanism=11 property is provided to the JCC driver, then there are two options for providing credentials to authenticate with Db2 Big SQL:
      • First, a principal and its password can be provided in the username and password properties.
      • Alternatively, the credentials can be obtained from the cached ticket granting ticket (TGT) in the Kerberos credentials cache, the location of which can optionally be specified by the KRB5CCNAME environment variable.
   3. Obtaining a ticket is performed by the kinit utility. On a Linux machine, the kinit can be performed using the default SUN JRE kinit utility or using the kinit utility in the IBM JRE. For example, on the Db2 Big SQL head note the kinit utility in the IBM JDK is located at /usr/ibmpacks/bigsql/5.x.x.x/db2/java/jdk64/jre/bin/kinit.
   4. The kinit utility itself can authenticate with the KDC using a principal and password, or a keytab file. For example, the following command authenticates with the Kerberos KDC using the bigsql user’s headless keytab:

      kinit -k -f -t /etc/security/keytabs/bigsql.headless.keytab bigsql-testcluster@IBM.COM

   5. On a Windows client machine one can use the kinit tool of the JGSS API of the IBM JRE which is invoked by the following command:

      java com.ibm.security.krb5.tools.Kinit

      The parameters are consistent with that on Linux, so per the previous example:

      java com.ibm.security.krb5.tools.Kinit
       -k -f -t /etc/security/keytabs/testuser1.keytab testuser1@IBM.COM

   6. Additionally, you can optionally pass the KerberosServerPrincipal=bigsql/<FQDN>@<realm_name> as the parameter while making connection using the DriverManager interface with a JDBC standalone program.

   Note:

   • It is important that the -f (for forwardable tickets) parameter is provided when using the IBM JRE, in particular.
   • The above steps can be performed for clients on the Db2 Big SQL head node, for example, JSQSH, and any other remote JDBC client applications, for example, DataStudio.
   • If you receive a CLIENT_NOT_FOUND error when connecting using the principal and password option, then this means that the principal specified in the username property does not exist in the Kerberos database. Instead, provide a valid Kerberos principal in the username property and retry.