Your Kerberos environment should be fully configured before you configure the driver for Kerberos authentication. You should refer to your SQL Server documentation and Java documentation for instructions on configuring Kerberos. For a Windows Active Directory implementation, you should also consult your Windows documentation. For a non-Entra ID 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 Entra ID implementation, Entra ID automatically obtains the TGT. However, for a non-Entra ID 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.
    • 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");
    • 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.
    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
  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: 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.

    Oracle JVM

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

    IBM JVM

    JDBC_DRIVER_01 {
  com.ibm.security.auth.module.Krb5LoginModule required useDefaultCcache=true;
};
  3. For Java SE 13 and higher, set the GSS client library to be used when communicating with the KDC. By default, the driver uses the GSS library and mechanisms provided by the JDK. However, you can also use the native GSS library for your platform by configuring the following Java system properties as described:
    Important: If you are using Windows Defender Credential Guard, you must set the Java system properties as described in this step.
    • Set sun.security.jgss.native to true.
    • For Microsoft SSPI, set javax.security.auth.useSubjectCredsOnly to false.
    • Optionally, set sun.security.jgss.lib to specify the absolute path of the native library file. If you do not provide a value, the JVM will load the default GSS library file for the platform.
      Note: Starting with Java SE 13, the native Windows interface will be Microsoft SSPI, and the GSS client library will be the sspi.bridge.dll file.
  4. Set the driver's AuthenticationMethod connection property to auto or kerberos. (See "AuthenticationMethod" for details.)
    Note: If your are configuring your environment for Kerberos Constrained Delegation (also known as impersonation), AuthenticationMethod must be set to kerberos.
  5. Optionally, set the ServicePrincipalName connection property if the default value built by the driver does not match the service principal name registered with the KDC.

    By default, the driver builds the ServicePrincipalName by concatenating the service name MSSQLSvc, the fully qualified domain name (FQDN) as specified with the ServerName property, the port number as specified with the PortNumber property, and the default realm name as specified in the Kerberos configuration file (krb5.conf). If this value 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 for the ServicePrincipalName property.

    The ServicePrincipalName takes the following form.

    Service_Name/Fully_Qualified_Domain_Name:Port_Number@REALM_NAME

    See "ServicePrincipalName" for details on the composition of the service principal name.

  6. Optionally, 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.

  7. Optionally, set the GSSCredential connection property for Kerberos constrained delegation (sometimes referred to as impersonation).

    Constrained delegation is a Kerberos mechanism that allows a client application to delegate authentication to a second service. See "Constrained delegation" for additional steps to configure your environment.

    AuthenticationMethod must be set to kerberos to use constrained delegation.