Configure JDBC clients on all platforms

Kerberos authentication on JDBC clients uses Java Authentication and Authorization Service (JAAS) and Security Support Provider Interface (SSPI) to acquire the initial Kerberos credentials.

Kerberos authentication for JDBC clients uses GSS authentication. The Vertica JDBC driver can acquire Kerberos credentials by using Java Authentication and Authorization Service (JAAS), or on Windows, by using native Security Support Provider Interface (SSPI) credentials.

JAAS is the default credential acquisition method and is supported on all platforms. On Windows, users can optionally use SSPI to authenticate with credentials from the current Windows logon session, without configuring a JAAS login file.

You specify the client login process through the JAAS Login Configuration File. This file contains options that specify the authentication method and other settings to use for Kerberos. A class called the LoginModule defines valid options in the configuration file.

The JDBC client principal is crafted as jdbc-username@server-from-connection-string.

Choose a Kerberos credential acquisition method

The JDBC driver supports the following Kerberos credential acquisition methods:

  • jaas: Uses Java Authentication and Authorization Service (JAAS). This is the default behavior and is supported on all platforms.

  • sspi: Uses Windows native Security Support Provider Interface (SSPI) credentials from the current Windows log in session. This option is supported only on Windows.

To use SSPI, set the kerberosauthtype connection property to sspi. If kerberosauthtype is not set, the driver uses the default JAAS-based behavior.

Use SSPI on Windows

On Windows, the JDBC driver uses native SSPI credentials for Kerberos authentication. This lets the driver authenticate using the credentials from the current Windows log in session and can remove the need for a separate JAAS login configuration.

To enable SSPI, set kerberosauthtype=sspi.

Example:

Properties props = new Properties();
props.setProperty("user", "kuser");
props.setProperty("KerberosServiceName", "vertica");
props.setProperty("KerberosHostName", "vcluster.example.com");
props.setProperty("kerberosauthtype", "sspi");

Connection conn = DriverManager.getConnection(
"jdbc:vertica://myserver.example.com:5433/VMart", props);

Troubleshooting

  • SSPI on non-Windows platforms: Authentication fails if you set kerberosauthtype=sspi on Linux or macOS as SSPI is supported only on Windows.

  • SSPI authentication failure on Windows: If SSPI authentication fails, verify that the client is joined to the correct domain and that the current Windows user has valid Kerberos credentials.

Implement the LoginModule for JAAS

We recommend that you use the JAAS public class com.sun.security.auth.module.Krb5LoginModul provided in the Java Runtime Environment (JRE).

The Krb5LoginModule authenticates users using Kerberos protocols and is implemented differently on non-Windows and Windows platforms:

  • On non-Windows platforms: The Krb5LoginModule defers to a native Kerberos client implementation. Thus, you can use the same /etc/krb5.conf setup as you use to configure ODBC and vsql clients on Linux and MAC OSX platforms.
  • On Windows platforms: The Krb5LoginModule uses a custom Kerberos client implementation bundled with the Java Runtime Environment (JRE). Windows settings are stored in a %WINDIR%\krb5.ini file, which has similar syntax and conventions to the non-Windows krb5.conf file. You can copy a krb5.conf from a non-Windows client to %WINDIR%\krb5.ini.

You can find documentation for the LoginModules in the com.sun.security.auth package, and on the Krb5LoginModule web page.

Create the JAAS login configuration

The JAASConfigName connection property identifies a specific configuration within a JAAS configuration that contains the Krb5LoginModule and its settings. The JAASConfigName setting lets multiple JDBC applications with different Kerberos settings coexist on a single host. The default configuration name is verticajdbc. The sections below describe JAAS-based Kerberos configuration. Follow these steps when kerberosauthtype is not set or is set to jaas.

You can configure JAAS-related settings in the java.security master security properties file. This file resides in the lib/security directory of the JRE. For more information, see Appendix A in the JavaTM Authentication and Authorization Service (JAAS) Reference Guide.

Create a JDBC login context

The following example shows how to create a login context for Kerberos authentication on a JDBC client. The client uses the default JAASConfigName of verticajdbc and specifies that:

  • The ticket-granting ticket will be obtained from the ticket cache

  • The user will not be prompted for a password if credentials cannot be obtained from the cache, keytab file, or through a shared state.

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

JDBC authentication request and connection

You can configure the Krb5LoginModule to use a cached ticket or keytab. The driver can also acquire a ticket or keytab automatically if the calling user provides a password.

In the preceding example, the login process uses a cached ticket and does not prompt for a password because both useTicketCache and doNotPrompt are set to true. If doNotPrompt=false and you provide a user name and password during the login process, the driver provides that information to the LoginModule. The driver then calls the kinit utility on your behalf.

  1. On a JDBC client, call the kinit utility to acquire a ticket:

    $ kinit kuser@EXAMPLE.COM

    If you prefer to use a password instead of calling the kinit utility, see the next section.

  2. Connect to Vertica:

    Properties props = new Properties();
props.setProperty("user", "kuser");
props.setProperty("KerberosServiceName", "vertica");
props.setProperty("KerberosHostName", "vcluster.example.com");
props.setProperty("JAASConfigName", "verticajdbc");
Connection conn = DriverManager.getConnection
"jdbc:vertica://myserver.example.com:5433/VMart", props);

Have the driver acquire a ticket

Sometimes, you may want to bypass calling the kinit utility yourself but still use encrypted, mutual authentication. In such cases, you can optionally pass the driver a clear text password to acquire the ticket from the KDC. The password is encrypted when sent across the network. For example, useTicketCache and doNotPrompt are both false in the following example. Thus, the calling user's credentials are not obtained through the ticket cache or keytab.

$ verticajdbc  {
  com.sun.security.auth.module.Krb5LoginModule
  required
  useTicketCache=false
  doNotPrompt=false;
};

The preceding example demonstrates the flexibility of JAAS. The driver no longer looks for a cached ticket, and you do not have to call kinit. Instead, the driver takes the password and user name and calls kinit on your behalf.

See also