Configuring the Driver for Kerberos Authentication

To configure the driver for Kerberos authentication, take the following steps.

1. Verify that your environment meets the requirements outlined in "Kerberos Authentication Requirements."

2. Modify your JAAS login configuration file to include the JAAS login module information needed for your environment. You can create your own login configuration file, or you can use the JDBCDriverLogin.conf file installed with the driver. This file is installed in the /lib directory of the product installation directory.

Note: For more information on the JAAS login configuration file, see "Java Authentication and Authorization Service (JAAS) Login Configuration File."

Whether you are using the JDBCDriverLogin.conf file or another file, the login configuration file must contain the entry JDBC_DRIVER_01 with JAAS login module information. The following examples show that the JAAS login module information depends on your JRE.

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. Once the JAAS configuration file includes the JAAS login module information, the file must be referenced using one of the following methods.

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. At least one of the login configuration files must include the JDBC_DRIVER_01 entry with the JAAS login module.

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

2. Find the line # Default login configuration file in the security properties file.

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

4. Set the Kerberos realm name and the KDC name for that realm using either of the following methods.

Note: If using Windows Active Directory, the Kerberos realm name is the Windows domain name and the KDC name is the Windows domain controller name.

Option 1. Modify the krb5.conf file to include the default realm name and the KDC name for that realm. (See "The krb5.conf File" for details about using and locating the krb5.conf file.)

For example, if the realm name is XYZ.COM and the KDC name is kdc1, your krb5.conf file would include the following entries.

[libdefaults]
default_realm = XYZ.COM

[realms]
XYZ.COM = {
kdc = kdc1
}

Option 2. Specify the Java system properties, java.security.krb5.realm and java.security.krb5.kdc, in your application. For example, if the realm name is XYZ.COM and the KDC name is kdc1, your application would include the following settings.

System.setProperty("java.security.krb5.realm","XYZ.COM");
System.setProperty("java.security.krb5.kdc","kdc1")

Even if you do not use the krb5.conf file to specify the realm and KDC names, you may need to modify your krb5.conf file to suit your environment. Refer to your database vendor documentation for information.

If you do not specify a valid Kerberos realm and a valid KDC name, the following exception is thrown.

Message:[DataDirect][MongoDB JDBC Driver]Could not establish a connection using
integrated security: No valid credentials provided

5. If you want the driver to use user credentials other than the server user’s operating system credentials, include code in your application to obtain and pass a javax.security.auth.Subject used for authentication. (See "Specifying User Credentials for Kerberos Authentication (Delegation of Credentials)" for details.)

6. Set the driver's AuthenticationMethod connection property to kerberos. (See "AuthenticationMethod" and "Using the AuthenticationMethod Property" for details.)

Note: When Kerberos authentication is enabled through the driver (AuthenticationMethod=kerberos), the driver automatically detects and abides by the server's SASL-QOP configuration at connection time. See "Kerberos SASL-QOP" for details.

7. Specify the service principal name with the ServicePrincipalName connection property. (See "ServicePrincipalName" for details on how to formulate and specify the service principal name.)

8. If using Kerberos authentication with a Security Manager on a Java Platform, you must grant security permissions to the application and driver. See "Permissions for Kerberos Authentication" for an example.

9. Establish a procedure for obtaining a Kerberos Ticket Granting Ticket (TGT) for your environment. (See "Obtaining a Kerberos Ticket Granting Ticket" for details.)

Scenario 1. If an application uses Kerberos authentication from a Windows client and Kerberos authentication is provided by Windows Active Directory, Windows Active Directory automatically obtains a TGT.

Scenario 2. When Kerberos authentication is provided by MIT Kerberos, you can allow the application to obtain a TGT in either of the following ways.

1. Automate the method of obtaining the TGT as with a keytab. (See your Kerberos documentation for details.)

2. Require the application user to obtain the TGT with a kinit command when logging on.

A TGT can be obtained with a kinit command to the Kerberos server. For example, the following command requests a TGT from the server with a lifetime of 10 hours, which is renewable for 5 days.

Note: The klist command can be used on Windows or UNIX/Linux systems to verify that a TGT has been obtained.