Vertica 26.3.x – Configure clients for Kerberos authentication

Security-and-Authentication: Configure ODBC and vsql clients on non-windows platforms

Mon, 01 Jan 0001 00:00:00 +0000

To configure an ODBC or vsql client on Linux or MAC OSX, you must first install the Kerberos 5 client package. See Kerberos authentication.

After you install the Kerberos 5 client package, you must provide clients with a valid Kerberos configuration file (krb5.conf). To communicate with the KDC, each client participating in Kerberos authentication must have a valid, identically configured krb5.conf file. The default location for the Kerberos configuration file is /etc/krb5.conf.

Tip

To enforce consistency among clients, Vertica, and the KDC, copy the /etc/krb5.conf file from the KDC to the client's/etc directory.

The Kerberos configuration (krb5.conf) file contains Kerberos-specific information, including:

How to reach the KDC
Default realm name
Domain
Path to log files
DNS lookup
Encryption types to use
Ticket lifetime

The default location for the Kerberos configuration file is /etc/krb5.conf.

When configured properly, the client can authenticate with Kerberos and retrieve a ticket through the kinit utility (see Acquire an ODBC Authentication Request and Connection below). Likewise, the server can then use ktutil to store its credentials in a keytab file

Authenticating ODBC and vsql clients requests and connections on non-windows platforms

ODBC and vsql use the client's ticket established by kinit to perform Kerberos authentication. These clients rely on the security library's default mechanisms to find the ticket file and the and Kerberos configuration file.

To authenticate against Kerberos, call the kinit utility to obtain a ticket from the Kerberos KDC server. The following two examples show how to send the ticket request using ODBC and vsql clients.

Acquire an ODBC authentication request and connection

On an ODBC client, acquire a ticket for the kuser user by calling the kinit utility.
```
$ kinit kuser@EXAMPLE.COM
Password for kuser@EXAMPLE.COM:
```

Connect to the database, and provide the principals in the connection string:

char outStr[100];
SQLLEN len;
SQLDriverConnect(handle, NULL, "Database=VMart;User=kuser;
Server=myserver.example.com;Port=5433;KerberosHostname=vcluster.example.com",
SQL_NTS, outStr, &len);

Acquire a vsql authentication request connection

If the vsql client is on the same machine you are connecting to, vsql connects through a UNIX domain socket. This connection bypasses Kerberos authentication. When you authenticate with Kerberos, especially if the client authentication method is configured as 'local', you must include the -h hostname option. See Command Line Options.

On the vsql client, call the kinit utility:

$ kinit kuser@EXAMPLE.COM
Password for kuser@EXAMPLE.COM:

Connect to the database, and provide the host and user principals in the connection string:

$ ./vsql -K vcluster.example.com -h myserver.example.com -U kuser
Welcome to vsql, the Vertica Analytic Database interactive terminal.

Type:  \h or \? for help with vsql commands
\g or terminate with semicolon to execute query
\q to quit

In the future, when you log in to vsql as kuser, vsql uses your cached ticket without prompting you for a password.

Verify the authentication method

You can verify the authentication method by querying the SESSIONS system table:

=> SELECT authentication_method FROM sessions;
 authentication_method
-----------------------
GSS-Kerberos
(1 row)

Security-and-Authentication: Configure ADO.NET, ODBC, and vsql clients on Windows

Mon, 01 Jan 0001 00:00:00 +0000

The Vertica client drivers support the Windows SSPI library for Kerberos authentication. Windows Kerberos configuration is stored in the registry.

You can choose between two different setup scenarios for Kerberos authentication on ODBC and vsql clients on Windows and ADO.NET:

Note

The procedures on this page are only relevant for ADO.NET drivers 12.0.4 and below. Later versions of the ADO.NET driver do not currently support Kerberos authentication.

Windows KDC on active directory with Windows built-in Kerberos client and the database

Kerberos authentication on Windows is commonly used with Active Directory, Microsoft's enterprise directory service/Kerberos implementation.Typically your organization's network or IT administrator performs the setup.

Windows clients have Kerberos authentication built into the authentication process. You do not need any additional software.

Your login credentials authenticate you to the Kerberos server (KDC) when you:

Log in to Windows from a client machine
Use a Windows instance that has been configured to use Kerberos through Active Directory

To use Kerberos authentication on Windows clients, log in as REALM\user.

Important

When you use the ADO.NET driver to connect to the database, you can optionally specify IntegratedSecurity=true in the connection string. This informs the driver to authenticate the calling user against the user's Windows credentials. As a result, you do not need to include a user name or password in the connection string. Any user=<username> entry to the connection string is ignored.

Linux KDC with Windows built-in Kerberos client and the database

A simple, but less common scenario is to configure Windows to authenticate against a non-Windows KDC. In this implementation, you use the ksetup utility to point the Windows operating system native Kerberos capabilities at a non-Active Directory KDC. By logging in to Windows, you obtain a ticket-granting ticket, similar to the Active Directory implementation. However, in this case, Windows is internally communicating with a Linux KDC. See the Microsoft Windows Server Ksetup page for more information.

When a database/windows user logs into their Windows machine (or after performing a kinit on Windows) the Kerberos ticket MUST have ok_as_delegate and forwardable flag set to be able to access webhdfs based external tables as follows:

$ CMD \> klist
#2>     Client: release @ VERT.LOCAL
Server: vertica/example.com @ VERT.LOCAL
KerbTicket Encryption Type: RSADSI RC4-HMAC(NT)
Ticket Flags 0x40a50000 forwardable renewable pre_authent ok_as_delegate name_canonicalize
Start Time: 9/27/2017 13:24:43 (local)
End Time:   9/27/2017 20:34:45 (local)
Renew Time: 10/3/2017 15:04:45 (local)
Session Key Type: RSADSI RC4-HMAC(NT)
Cache Flags: 0
Kdc Called: ADKDC01

Note

The Ticket Flags setting above must contain ok_as_delegate and forwardable entries. For information on these parameters see Kerberos documentation.

Configure Windows clients for Kerberos authentication

Depending on which implementation you want to configure, refer to one of the following pages on the Microsoft Server website:

To set up Windows clients with Active Directory, refer to Step-by-Step Guide to Kerberos 5 (krb5 1.0) Interoperability.
To set up Windows clients with the ksetup utility, refer to the Ksetup page.

Authenticate and connect clients

The KDC can authenticate both an ADO.NET and a vsql client.

Note

Use the fully-qualified domain name as the server in your connection string; for example, use host.example.com instead of just host. That way, if the server moves location, you do not have to change your connection string.

Verify an ADO.NET authentication request and connection

This example shows how to use the IntegratedSecurity=true, setting to specify that the ADO.NET driver authenticate the calling user's Windows credentials:

VerticaConnection conn = new
VerticaConnection("Database=VMart;Server=host.example.com;
Port=5433;IntegratedSecurity=true;
KerberosServiceName=vertica;KerberosHostname=vcluster.example.com");
conn.open();

Verify a vsql authentication request and connection

Run the vsql client and supply the connection string to the database:

C:\Users\kuser\Desktop>vsql.exe -h host.example.com -K vcluster -U kuser

Welcome to vsql, the Vertica Analytic Database interactive terminal.
Type:  \h or \? for help with vsql commands
\g or terminate with semicolon to execute query
\q to quit

Security-and-Authentication: Configure JDBC clients on all platforms

Mon, 01 Jan 0001 00:00:00 +0000

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);

Note

SSPI is supported only on Windows. On Linux and macOS, use JAAS-based Kerberos authentication.

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.

Note

If kerberosauthtype is not set, the driver preserves the existing JAAS-based behavior. SSPI is used only when you set kerberosauthtype=sspi.

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.

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.

Important

Carefully construct the JAAS login configuration file. If syntax is incorrect, authentication fails.

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 Java^TM Authentication and Authorization Service (JAAS) Reference Guide.

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.

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.

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.

Vertica 26.3.x – Configure clients for Kerberos authentication

Security-and-Authentication: Configure ODBC and vsql clients on non-windows platforms

Tip

Authenticating ODBC and vsql clients requests and connections on non-windows platforms

Acquire an ODBC authentication request and connection

Acquire a vsql authentication request connection

Verify the authentication method

See also

Security-and-Authentication: Configure ADO.NET, ODBC, and vsql clients on Windows

Note

Windows KDC on active directory with Windows built-in Kerberos client and the database

Important

Linux KDC with Windows built-in Kerberos client and the database

Note

Configure Windows clients for Kerberos authentication

Authenticate and connect clients

Note

Verify an ADO.NET authentication request and connection

Verify a vsql authentication request and connection

See also

Security-and-Authentication: Configure JDBC clients on all platforms

Choose a Kerberos credential acquisition method

Use SSPI on Windows

Note

Troubleshooting

Note

Implement the LoginModule for JAAS

Important

JDBC authentication request and connection

Have the driver acquire a ticket

See also

Vertica 26.3.x – Configure clients for Kerberos authentication

Security-and-Authentication: Configure ODBC and vsql clients on non-windows platforms

Tip

Authenticating ODBC and vsql clients requests and connections on non-windows platforms

Acquire an ODBC authentication request and connection

Acquire a vsql authentication request connection

Verify the authentication method

See also

Security-and-Authentication: Configure ADO.NET, ODBC, and vsql clients on Windows

Note

Windows KDC on active directory with Windows built-in Kerberos client and the database

Important

Linux KDC with Windows built-in Kerberos client and the database

Note

Configure Windows clients for Kerberos authentication

Authenticate and connect clients

Note

Verify an ADO.NET authentication request and connection

Verify a vsql authentication request and connection

See also

Security-and-Authentication: Configure JDBC clients on all platforms

Choose a Kerberos credential acquisition method

Use SSPI on Windows

Note

Troubleshooting

Note

Implement the LoginModule for JAAS

Create the JAAS login configuration

Important

Create a JDBC login context

JDBC authentication request and connection

Have the driver acquire a ticket

See also