Configuring the driver for Kerberos authentication

Your Kerberos environment should be fully configured before you configure the driver for Kerberos authentication. You should refer to your Apache Hive and Java documentation for instructions on configuring Kerberos. For a Windows Active Directory implementation, you should also consult your Windows documentation. For a non-Active Directory implementation (on a Windows or non-Windows operating system), you should consult MIT Kerberos documentation.

Important: A properly configured Kerberos environment must include a means of obtaining a Kerberos Ticket Granting Ticket (TGT). For a Windows Active Directory implementation, Active Directory automatically obtains the TGT. However, for a non-Active Directory implementation, the means of obtaining the TGT must be automated or handled manually.

Once your Kerberos environment has been configured, take the following steps to configure the driver.

1. Use one of the following methods to integrate the JAAS configuration file into your Kerberos environment. (See "The JAAS Login Configuration File" for details.)

Note: The install_dir/lib/JDBCDriverLogin.conf file is the JAAS login configuration file installed with the driver. You can use this file or another file as your JAAS login configuration file.

Note: Regardless of operating system, forward slashes must be used when designating the path of the JAAS login configuration file.

Option 1. Specify a login configuration file directly in your application with the java.security.auth.login.config system property. For example:

System.setProperty("java.security.auth.login.config","install_dir/lib/JDBCDriverLogin.conf");

Option 2. Set up a default configuration. Modify the Java security properties file to indicate the URL of the login configuration file with the login.config.url.n property where n is an integer connoting separate, consecutive login configuration files. When more than one login configuration file is specified, then the files are read and concatenated into a single configuration.

a. Open the Java security properties file. The security properties file is the java.security file in the /jre/lib/security directory of your Java installation.

c. Below the # Default login configuration file line, add the URL of the login configuration file as the value for a login.config.url.n property. For example:

# Default login configuration file
login.config.url.1=file:${user.home}/.java.login.config
login.config.url.2=file:install_dir/lib/JDBCDriverLogin.conf

2. Ensure your JAAS login configuration file includes an entry with authentication technology that the driver can use to establish a Kerberos connection. (See "The JAAS login configuration file" for details.)

Note: For Apache ZooKeeper users: All the steps provided in this procedure apply to Apache ZooKeeper as well, except the steps about adding entry to the JAAS login configuration file. To know how to add an entry for Kerberos authentication in the JAAS login configuration file for Apache ZooKeeper, see "Configuring Apache ZooKeeper for Kerberos authentication."

Note: The JAAS login configuration file installed with the driver (install_dir/lib/JDBCDriverLogin.conf) includes a default entry with the name JDBC_DRIVER_01. This entry specifies the Kerberos authentication technology used with an Oracle JVM.

The following examples show that the authentication technology used in a Kerberos environment depends on your JVM.

JDBC_DRIVER_01 {
com.sun.security.auth.module.Krb5LoginModule required useTicketCache=true;
};

JDBC_DRIVER_01 {
com.ibm.security.auth.module.Krb5LoginModule required useDefaultCcache=true;
};

3. Set the driver's AuthenticationMethod connection property to kerberos. (See "AuthenticationMethod" for details.)

4. Optionally, set the ServicePrincipalName property to the case-sensitive service principal name to be used for Kerberos authentication. By default, the driver provides a value for ServicePrincipalName based on the value of the server name property using the format hive/server_name. If the default does not match the service principal name registered with the KDC, then the value of the service principal name registered with the KDC should be specified.

Note: The service principal name is the value of the hive.server2.authentication.kerberos.principal property in the hive-site.xml file.

The value of the ServicePrincipalName property can include the Kerberos realm name, but it is optional. If you do not specify the realm name, the default realm is used. For example, if the service principal name, including Kerberos realm name, is server/Hive125ase1@XYZ.COM and the default realm is XYZ.COM, valid values for this property are:

5. Set the LoginConfigName connection property if the name of the JAAS login configuration file entry is different from the driver default JDBC_DRIVER_01. (See "The JAAS Login Configuration File" and "LoginConfigName" for details.)

JDBC_DRIVER_01 is the default entry name for the JAAS login configuration file (JDBCDriverLogin.conf) installed with the driver. When configuring your Kerberos environment, your network or system administrator may have used a different entry name. Check with your administrator to verify the correct entry name.

6. Set the User connection property as appropriate. (See "User" for details.)

In most circumstances, there is no need to set the User connection property. By default, the driver uses the user principal name in the Kerberos Ticket Granting Ticket (TGT) as the value for the User property.

7. Set the DatabaseName connection property as appropriate. (See "DatabaseName" for details.)