Each supported platform has a different security framework. Thus, the steps required to configure and authenticate against Kerberos differ among clients.
On the server side, you construct the Vertica Kerberos service name principal using this format:
A few scenarios exist in which the Vertica server principal name might not match the host name in the connection string. See Troubleshooting Kerberos Authentication for more information.
1 - Configure ODBC and vsql clients on non-windows platforms
To configure an ODBC or vsql client on Linux or MAC OSX, you must first install the Kerberos 5 client package.
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 Analytic Database, 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 Vertica, and provide the principals in the connection string:
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 Vertica, 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)
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 Vertica
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 Vertica, 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 Vertica
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:
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
Log in to your Windows client, for example, as EXAMPLE\kuser.
Run the vsql client and supply the connection string to Vertica:
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
Kerberos authentication on JDBC clients uses Java Authentication and Authorization Service (JAAS) to acquire the initial Kerberos credentials.
Kerberos authentication on JDBC clients uses Java Authentication and Authorization Service (JAAS) to acquire the initial Kerberos credentials. JAAS is an API framework that hides platform-specific authentication details and provides a consistent interface for other applications.
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.
Implement the LoginModule
Vertica recommends 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.
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 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.
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.
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.
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.