Kerberos authentication

• 1: Configure Vertica for Kerberos authentication
• 1.1: Create the Vertica principals and keytabs on Linux KDC
• 1.2: Specify KDC information and configure realms
• 1.3: Inform Vertica about the Kerberos principal
• 1.4: Configure the authentication method for all clients
• 1.5: Creating the principals and keytab on active directory
• 1.6: Get the Kerberos ticket and authenticate Vertica
• 2: Configure clients for Kerberos authentication
• 2.1: Configure ODBC and vsql clients on non-windows platforms
• 2.2: Configure ADO.NET, ODBC, and vsql clients on Windows
• 2.3: Configure JDBC clients on all platforms
• 3: Troubleshooting Kerberos authentication
• 4: Configuring Kerberos authentication

192.168.1.101 v_vmart_node0001.example.com v_vmart_node0001

=> ALTER AUTHENTICATION krb_auth_users set REALM='USERS.COM';
=> ALTER AUTHENTICATION krb_auth_realmad set REALM='REALM_AD.COM';

=> SELECT * FROM client_auth;
auth_oid | auth_name | is_auth_enabled | auth_host_type | auth_host_address | auth_method | auth_parameters     | auth_priority
---------+-----------+-----------------+----------------+-------------------+-------------+-----------------+-----------------
45035996 | krb001    |   True          |   HOST         |  0.0.0.0/0        |  GSS        | realm=USERS.COM     |  0
45035997 | user_auth |   True          |   LOCAL        |                   |  TRUST      |                     |  1000
45035737 | krb002    |   True          |   HOST         |  0.0.0.0/0        |  GSS        | realm=REALM_AD.COM  |  1

1 - Configure Vertica for Kerberos authentication

Kerberos provides a strong cryptographic authentication against the devices which lets the client & servers to communicate in a more secured manner. It addresses network security problems.

Your system must have one or more Kerberos Key Distribution Centers (KDC) installed and configured. The KDCs must be accessible from every node in your Vertica Analytic Database cluster.

The KDC must support Kerberos 5 using GSS-API. For details, see the MIT Kerberos Distribution Page.

In this section

1.1 - Create the Vertica principals and keytabs on Linux KDC

Vertica uses service principals for system-level operations. These principals identify the Vertica service and are used as follows:

• Kerberized Vertica clients request access to this service when they authenticate to the database.

• System processes like the Tuple Mover use this identity when they authenticate to external services such as Hadoop.

Create principals and keys as follows:

1. Start the Kerberos 5 database administration utility (kadmin or kadmin.local) to create Vertica principals on a Linux KDC.

   • Use kadmin if you are accessing the KDC on a remote server. If you have access to the Kerberos administrator password, you can use kadmin on any machine where the Kerberos 5 client package is installed. When you start kadmin, the utility prompts you for the Kerberos administrator's password. You might need root privileges on the client to run kadmin.

   • Use kadmin.local if:

     • The KDC is on the machine that you are logging in to.

     • You have root privileges on that server.

   kadmin.local does not require the administrators login credentials.

   For more information about the kadmin and kadmin.local commands, see the kadmin documentation.

2. Create one service principal for Vertica on each node. The host name must match the value supplied by the operating system. The following example creates the service principal vertica for the node named v_vmart_node0001.example.com:

   $ sudo /usr/kerberos/sbin/kadmin.local
   kadmin.local add_principal vertica/v_vmart_node0001.example.com
   

   Repeat the ktadd command once per principal. You can create separate keytabs for each principal user or add them all to a single keytab file (such as krb5.keytab). If you are using a single file, see the documentation for the -glob option in the MIT Kerberos documentation.

   You must have a user principal for each Vertica Analytic Database user that uses Kerberos Authentication. For example:

   $ sudo /usr/kerberos/sbin/kadmin.local
   kadmin.local add_principal [options] VerticaUser1
   

3. Copy each keytab file to the /etc folder on the corresponding cluster node. Use the same path and file name on all nodes.

4. On each node, make the keytab file readable by the file owner who is running the database process (typically, the Linux dbadmin user). For example, you can change ownership of the files to dbadmin as follows:

   $ sudo chown dbadmin *.keytab
   

   Important

   In a production environment, you must control who can access the keytab file to prevent unauthorized users from delegating your server. For more information about delegation (also known as impersonation), see Technet.Microsoft.com.

   After you create a keytab file, you can use the klist command to view keys stored in the file:

   $ sudo /usr/kerberos/bin/klist -ke -t
   Keytab name: FILE:/etc/krb5.keytab
   KVNO    Timestamp        Principal
   ---- ------------------- --------------------------------------------------------------------------
   4     08/15/2017 7:35:41 vertica/v_vmart_node0001.example.com@EXAMPLE.COM (aes256-cts-hmac-sha1-96)
   4     08/15/2017 7:35:41 vertica/v_vmart_node0001.example.com@EXAMPLE.COM (aes128-cts-hmac-sha1-96)
   

5. On Vertica run the following to ensure the Kerberos parameters are set correctly:

   => select parameter_name, current_value from configuration_parameters where parameter_name like 'Ker%';
   parameter_name         |                      current_value
   -----------------------+---------------------------------------------------------------------
   KerberosHostname       | v_vmart_node0001.example.com
   KerberosKeytabFile     | /etc/krb5.keytab
   KerberosRealm          | EXAMPLE.COM
   KerberosTicketDuration | 0
   KerberosServiceName    | vertica
   (5 rows)
   

6. Ensure that all clients use the gss authentication method.

   From Vertica:

   => CREATE USER bob;
   CREATE USER
   
   => CREATE AUTHENTICATION v_kerberos method 'gss' host '0.0.0.0/0';
   CREATE AUTHENTICATION
   
   => ALTER AUTHENTICATION v_kerberos enable;
   ALTER AUTHENTICATION
   
   => GRANT AUTHENTICATION v_kerberos to bob;
   GRANT AUTHENTICATION
   

   From the operating system command line:

   $ kinit bob
   
   $ vsql -U bob -k vertica -K v_vmart_node0001.example.com -h v_vmart_node0001 -c "select client_authentication_name,
   authentication_method from sessions;"
    client_authentication_name | authentication_method--
   ----------------------------+-----------------------
    v_kerberos                 |    GSS-Kerberos
   
   (1 row)
   

7. On Vertica, run KERBEROS_CONFIG_CHECK to verify the Kerberos configuration. KERBEROS_CONFIG_CHECK verifies the following:

   • The existence of the kinit and kb5.conf files.

   • Whether the keytab file exists and is set

   • The Kerberos configuration parameters set in the database:

     • KerberosServiceName

     • KerberosHostname

     • KerberosRealm

     • Vertica Principal

   • That Kerberos can read the Vertica keys

   • That Kerberos can get the tickets for the Vertica principal

   • That Vertica can initialize the keys with kinit

1.2 - Specify KDC information and configure realms

Each client and Vertica Analytic Database server in the Kerberos realm must have a valid, identically configured Kerberos configuration (krb5.conf) file. Without this file, the client does not know how to reach the KDC.

If you use Microsoft Active Directory, you do not need to perform this step. Refer to the Kerberos documentation for your platform for more information about the Kerberos configuration file on Active Directory.

At a minimum, you must configure the following sections in the krb5.conf file.

• [libdefaults]—Settings used by the Kerberos 5 library
• [realms]—Realm-specific contact information and settings
• [domain_realm]—Maps server hostnames to Kerberos realms

See the Kerberos documentation for information about other sections in this configuration file.

You must update the /etc/krb5.conf file to reflect your site's Kerberos configuration. The simplest way to enforce consistency among all clients and servers in the Kerberos realm is to copy the /etc/krb5.conf file from the KDC. Then, place this file in the /etc directory on each Vertica cluster node.

1.3 - Inform Vertica about the Kerberos principal

Follow these steps to inform Vertica about the principal name and keytab location.

For information about the parameters that you are setting in this procedure, see Kerberos configuration parameters.

1. Log in to the database as an administrator (typically dbadmin).

2. Set the KerberosKeyTabFile configuration parameter to point to the location of the keytab file:

   => ALTER DATABASE DEFAULT SET PARAMETER KerberosKeytabFile = '/etc/krb5.keytab';
   

   The keytab file must be in the same location (/etc/krb5.keytab in this example) on all nodes.

3. Set the service name for the Vertica principal; for example, vertica:

   => ALTER DATABASE DEFAULT SET PARAMETER KerberosServiceName = 'vertica';
   

4. Provide the realm portion of the principal, for example, EXAMPLE.COM:

   => ALTER DATABASE DEFAULT SET PARAMETER KerberosRealm = 'EXAMPLE.COM'
   

1.4 - Configure the authentication method for all clients

To make sure that all clients use the gss authentication method, run the following statements:

=> CREATE AUTHENTICATION <method_name> METHOD 'gss' HOST '0.0.0.0/0';
=> GRANT AUTHENTICATION <method_name> TO Public;

For more information, see Implementing Client Authentication.

1.5 - Creating the principals and keytab on active directory

Active Directory stores information about members of the Windows domain, including users and hosts.

Vertica uses the Kerberos protocol to access this information in order to authenticate Windows users to the Vertica database. The Kerberos protocol uses principals to identify users and keytab files to store their cryptographic information. You need to install the keytab files into Vertica to enable the Vertica database to cryptographically authenticate windows users.

This procedure describes:

• Creating a Vertica service principal.

• Exporting the keytab files for these principals

• Installing the keytab files in the Vertica database. This allows Vertica to authenticate Windows users and grant them access to the Vertica database.

1. Create a Windows account (principal) for the Vertica service and one Vertica host for each node/host in the cluster. This procedure creates Windows accounts for host verticanode01 and service vertica running on this node.
   

   When you create these accounts, select the following:
   

   • User cannot change password

   • Password never expires

   Note

   You can deselect Password never expires. However, if you change these user passwords, you must recreate the keytab files and reinstall them into Vertica. This includes repeating the entire procedure.

2. If you are using external tables on HDFS that are secured by Kerberos authentication, you must enable Delegation. To do so, access the Active Directory Users and Computers dialog, right-click the Windows account (principal) for the Vertica service, and select Delegation. Trust this user for delegation to any service.
   

3. Run the following command to create the keytab for the host verticanode01.dc.com node/host:

   $ ktpass -out ./host.verticanode01.dc.com.keytab -princ host/verticanode01.dc.com@DC.COM -mapuser verticanode01
    -mapop set -pass secret  -ptype KRB5_NT_SRV_HST
   

4. Run the following command to create the keytab for the vertica service:

   $ ktpass -out ./vertica.verticanode01dc.com.keytab -princ vertica/verticanode01.dc.com@DC.COM -mapuser vertica
    -mapop set -pass secret  -ptype KRB5_NT_PRINCIPAL
   

   For more information about keytab files, see Technet.Microsoft.com.

5. Run the following commands to verify that the service principal name is mapped correctly. You must run these commands for each node in your cluster:

   $ setspn -L vertica
       Registered ServicePrincipalNamefor CN=vertica,CN=Users,DC=dc,DC=com
         vertica/verticanode01.dc.com
   
   $ setspn -L verticanode01
       Registered ServicePrincipalNamefor CN=verticanode01,CN=Users,DC=dc,DC=com
         host/verticanode01.dc.com
   

6. Copy the keytabs you created above, vertica.verticanode01.dc.com.keytab and host.verticanode01.dc.com.keytab, to the Linux host verticanode01.dc.com.

7. Combine the keytab files into a single keytab:

   
   [release@vertica krbTest]$ /usr/kerberos/sbin/ktutil
   ktutil:  rkt host.verticanode01.dc.com.keytab
   ktutil:  rkt vertica.verticanode01.dc.com.keytab
   ktutil:  list
   slot KVNO Principal
   ---- ---- ---------------------------------------------------------------------
     1    3  host/verticanode01.dc.com@DC.COM
     2   16  vertica/verticanode01.dc.com@DC.COM
   ktutil:  wkt verticanode01.dc.com.keytab
   ktutil:  exit
   

   This creates a single keytab file that contains the server principal for authentication.

8. Copy the new keytab file to the catalog directory. For example:

   $ cp verticanode01.dc.com.keytab /home/dbadmin/VMart/v_vmart_nodennnn_catalog
   

9. Test the keytab file's ability to retrieve a ticket to ensure it works from the Vertica node:

   
   $ kinit vertica/verticanode01.dc.com -k -t verticanode01.dc.com.keytab
   $ klist
   
   Ticket cache: KFILE:/tmp/krb_ccache_1003
   Default principal: vertica/verticanode01.dc.com@DC.COM
   
   Valid starting Expires Service principal
   04/08/2017 13:35:25 04/08/2017 23:35:25 krbtgt/DC.COM@DC.COM
                   renew until 04/15/2017 14:35:25
   

   When the ticket expires or not automatically retrieved you need to manually run the kinit command. See Get the Kerberos ticket and authenticate Vertica.

10. Set the right permissions and ownership on the keytab files:

    $ chmod 600 verticanode01.dc.com.keytab
    $ chown dbadmin:verticadba verticanode01.dc.com.keytab
    

11. Set the following Kerberos configuration parameters using ALTER DATABASE to inform Vertica about the Kerberos principal:
    

    KerberosKeytabFile=<CATALOGDIR>/verticanode01.dc.com.keytab
    KerberosRealm=DC.COM
    KerberosServiceName=vertica
    KerberosTicketDuration = 0
    KerberosHostname=verticanode01.dc.com
    

12. Restart the Vertica server.

13. Test your Kerberos setup as follows to ensure that all clients use the gss authentication method.
    
    From Vertica:

    => CREATE USER windowsuser1;
    CREATE USER
    
    => CREATE AUTHENTICATION v_kerberos method 'gss' host '0.0.0.0/0';
    CREATE AUTHENTICATION
    
    => ALTER AUTHENTICATION v_kerberos enable;
    ALTER AUTHENTICATION
    
    => GRANT AUTHENTICATION v_kerberos to windowsuser1;
    GRANT AUTHENTICATION
    

    From the operating system command line:

    $ kinit windowsuser1
    
    $ vsql -U windowsuser1 -k vertica -K verticanode01.dc.com -h verticanode01.dc.com -c "select client_authentication_name,
    authentication_method from sessions;"
     client_authentication_name | authentication_method--
    ----------------------------+-----------------------
     v_kerberos                 |    GSS-Kerberos
    
    (1 row)
    

14. Run KERBEROS_CONFIG_CHECK to verify the Kerberos configuration. KERBEROS_CONFIG_CHECK verifies the following:

    • The existence of the kinit and kb5.conf files.

    • Whether the keytab file exists and is set

    • The Kerberos configuration parameters set in the database:

      • KerberosServiceName

      • KerberosHostname

      • KerberosRealm

      • Vertica Principal

    • That Kerberos can read the Vertica keys

    • That Kerberos can get the tickets for the Vertica principal

    • That Vertica can initialize the keys with kinit
      

1.6 - Get the Kerberos ticket and authenticate Vertica

If your organization uses Kerberos as part of the login process, Kerberos tickets are automatically retrieved upon login. Otherwise, you need to run kinit to retrieve the Kerberos ticket.

The following example shows how to retrieve the ticket and authenticate Vertica Analytic Database with the KDC using the kinit command. EXAMPLE.COM is the realm name. You must use the realm name with your username to retrieve a Kerberos ticket. See Specify KDC information and configure realms.

$ kinit
Password for principal_user@EXAMPLE.COM: kpasswd

You are prompted for the password of the principal user name created when you created the principals and keytabs (see Create the Vertica principals and keytabs on Linux KDC).

The Kerberos ticket gets cached for a pre-determined length of time. See Ticket Management in the Kerberos documentation for more information on setting expiration parameters.

Upon expiration, you need to run the kinit command again to retrieve another Kerberos ticket.

2 - Configure clients for Kerberos authentication

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:

Kerberos_Service_Name/Kerberos_Host_Name@Kerberos_Realm

For each client, the GSS libraries require the following format for the Vertica service principal:

Kerberos_Service_Name@Kerberos_Host_Name

You can omit the realm portion of the principal because GSS libraries use the realm name of the configured default (Kerberos_Realm) realm.

For information about client connection strings, see the following topics:

• Data source name (DSN) connection properties
• JDBC connection properties
• ADO.NET connection properties

• (vsql) Command-line options

In this section

• Configure ODBC and vsql clients on non-windows platforms

• Configure ODBC and vsql Clients on Windows and ADO.NET

• Configure JDBC Clients on all Platforms

2.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. See Configuring 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.

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

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

2. Connect to Vertica, 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.

1. On the vsql client, call the kinit utility:

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

2. 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)

See also

• Data source name (DSN) connection properties

• (vsql) Command-line options

2.2 - Configure ADO.NET, ODBC, and vsql clients on Windows

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:

• Windows KDC on Active Directory with Windows Built-in Kerberos Client and

• Linux KDC with Windows Built-in Kerberos Client and

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.

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:

$ CMD \> klist
#2>     Client: release @ VERTQA.LOCAL
Server: vertica/vqatest108.verticacorp.com @ VERTQA.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

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.

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

1. Log in to your Windows client, for example, as EXAMPLE\kuser.

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

See also

• Kerberos authentication
• Command-line options
• ADO.NET connection properties

2.3 - Configure JDBC clients on all platforms

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.

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.

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

• Kerberos Client/Server Requirements

• JDBC connection properties

• Java^TM Authentication and Authorization Service (JAAS) Reference Guide (external website)

3 - Troubleshooting Kerberos authentication

These tips can help you avoid issues related to Kerberos authentication with Vertica and to troubleshoot any problems that occur.

JDBC client authentication fails

If Kerberos authentication fails on a JDBC client, check the JAAS login configuration file for syntax issues. If syntax is incorrect, authentication fails.

Working domain name service (DNS) not configured

Verify that the DNS entries and the system host file (/etc/hosts or /etc/hostnames) on the network are all properly configured for your environment. If you are using a fully qualified domain name, ensure that is properly configured as well. Refer to the Kerberos documentation for your platform for details.

System clocks out of sync

System clocks in your network must remain in sync for Kerberos authentication to work properly. If you access data in HDFS, then Vertica nodes must also be in sync with Hadoop.

All systems except red hat 7/CentOS 7

To keep system clocks in sync:

1. Install NTP on the Kerberos server (KDC).

2. Install NTP on each server in your network.

3. Synchronize system clocks on all machines that participate in the Kerberos realm within a few minutes of the KDC and each other

Clock skew can be a problem on Linux virtual machines that need to sync with the Windows Time Service. Use the following stepsto keep time in sync:

1. Using any text editor, open /etc/ntp.conf.

2. Under the Undisciplined Local Clock section, add the IP address for the Vertica server. Then, remove existing server entries.

3. Log in to the server as root, and set up a cron job to sync time with the added IP address every half hour, or as often as needed. For example:

   # 0 */2 * * * /etc/init.d/ntpd restart
   

4. Alternatively, run the following command to force clock sync immediately:

   $ sudo /etc/init.d/ntpd restart
   

For more information, see Enabling network time protocol (NTP) and the Network Time Protocol website.

Red hat 7/CentOS 7 systems

In Red Hat 7/CentOS 7, ntpd is deprecated in favor of chrony. To keep system clocks in your network in sync for Kerberos authentication to work properly, do the following:

1. Install chrony on the Kerberos server (KDC).

2. Install chrony on each server in your network.

3. Synchronize system clocks on all machines that participate in the Kerberos realm within a few minutes of the KDC and each other.

Clock skew on Linux virtual machines

Clock skew can be problematic on Linux virtual machines that need to sync with the Windows Time Service. Try the following to keep time in sync:

1. Using any text editor, open /etc/chrony.conf.

2. Under the Undisciplined Local Clock section, add the IP address for the Vertica server. Then, remove existing server entries.

3. Log in to the server as root, and set up a cron job to sync time with the added IP address every half hour, or as often as needed. For example:

   # 0 */2 * * * systemctl start chronyd
   

4. Alternatively, run the following command to force clock sync immediately:

   $ sudo systemctl start chronyd
   

For more information, see the Red Hat chrony guide.

Kerberos ticket is valid, but Hadoop access fails

Vertica uses Kerberos tickets to obtain Hadoop tokens. It then uses the Hadoop tokens to access the Hadoop data. Hadoop tokens expire after a period of time, so Vertica periodically refreshes them. However, if your Hadoop cluster is set to expire tokens frequently, it is possible that tokens might not be refreshed in time. If the token expires, you cannot access data.

Setting the HadoopFSTokenRefreshFrequency configuration parameter allows you to specify how often Vertica should refresh the token. Specify this value, in seconds, to be smaller than the expiration period set for Hadoop. For example:

=> ALTER DATABASE exampledb SET HadoopFSTokenRefreshFrequency = '86400';

For another cause of Hadoop access failure, see System Clocks Out of Sync.

Encryption algorithm choices

Kerberos is based on symmetric encryption. Be sure that all Kerberos parties used in the Kerberos realm agree on the encryption algorithm to use. If they do not agree, authentication fails. You can review the exceptions in the vertica.log.

On a Windows client, be sure the encryption types match the types set on Active Directory. See Configure Vertica for Kerberos authentication.

Be aware that Kerberos is used only for securing the login process. After the login process completes, by default, information travels between client and server without encryption. If you want to encrypt traffic, use SSL. For details, see Implementing SSL.

Kerberos passwords not recognized

If you change your Kerberos password, you must re-create all of your keytab files.

Using the ODBC data source configuration utility

On Windows vsql clients, you may choose to use the ODBC Data Source Configuration utility and supply a client Data Source. If so, be sure you enter a Kerberos host name in the Client Settings tab to avoid client connection failures with the Vertica Analytic Database server.

Authentication failure in backup, restore, or admin tools

This problem can arise in configurations where each Vertica node uses its own Kerberos principal. (This configuration is recommended.) When using vbr or admintools you might see an error such as the following:

$ vsql: GSSAPI continuation error: Miscellaenous failure
GSSAPI continuation error: Server not found in Kerberos database

Backup/restore and the admin tools use the value of KerberosHostname, if it is set, in the Kerberos principal used to authenticate. The same value is used on all nodes. If you have defined one Kerberos principal per node, as recommended, this value does not match. To correct this, unset the KerberosHostname parameter:

=> ALTER DATABASE DEFAULT CLEAR KerberosHostname;

Server's principal name does not match host name

This problem can arise in configurations where a single Kerberos principal is used for all nodes. Vertica recommends against using a single Kerberos principal for all nodes. Instead, use one principal per node and do not set the KerberosHostname parameter.

In some cases during client connection, the Vertica server's principal name might not match the host name in the connection string. (See also Using the ODBC Data Source Configuration Utility in this topic.)

On Windows vsql clients, you may choose to use the ODBC Data Source Configuration utility and supply a client Data Source. If so, be sure you enter a Kerberos host name in the Client Settings tab to avoid client connection failures with the Vertica server.

On ODBC, JDBC, and ADO.NET clients, set the host name portion of the server's principal using the KerberosHostName connection string.

Principal/host mismatch issues and resolutions

The following issues can occur if the principal and host are mismatched.

The KerberosHostName configuration parameter has been overridden

For example, consider the following connection string:

jdbc:vertica://v_vmart_node0001.example.com/vmart?user=kuser

Because the this connection string includes no explicit KerberosHostName parameter, the driver defaults to the host in the URL (v_vmart_node0001.example.com). If you overwrite the server-side KerberosHostName parameter as “abc”, the client generates an incorrect principal.

To resolve this issue, explicitly set the client’s KerberosHostName to the connection string, as in this example:

jdbc:vertica://v_vmart_node0001.example.com/vmart?user=kuser&kerberoshostname=abc

Connection load balancing is enabled... but the node against which the client authenticates might not be the node in the connection string.

In this situation, consider changing all nodes to use the same KerberosHostName setting. When you use the default to the host that was originally specified in the connection string, load balancing cannot interfere with Kerberos authentication.

A DNS name does not match the Kerberos host name

For example, imagine a cluster of six servers, where you want hr-servers and finance-servers to connect to different nodes on the Vertica cluster. Kerberos authentication, however, occurs on a single (the same) KDC. In the following example, the Kerberos service host name of the servers is server.example.com.

Suppose you have the following list of example servers:

server1.example.com 192.16.10.11
server2.example.com 192.16.10.12
server3.example.com 192.16.10.13
server4.example.com 192.16.10.14
server5.example.com 192.16.10.15
server6.example.com 192.16.10.16

Now, assume you have the following DNS entries:

finance-servers.example.com 192.168.10.11, 192.168.10.12, 192.168.10.13
hr-servers.example.com 192.168.10.14, 192.168.10.15, 192.168.10.16

When you connect to finance-servers.example.com, specify:

• Kerberos -h host name option as server.example.com

• -K host option for hr-servers.example.com

For example:

$ vsql -h finance-servers.example.com -K server.example.com

No DNS is set up on the client machine... so you must connect by IP only

To resolve this issue, specify:

• Kerberos -h host name option for the IP address

• -K host option for server.example.com

For example:

$ vsql -h 192.168.1.12 -K server.example.com

There is a load balancer involved (Virtual IP)... but there is no DNS name for the VIP

Specify:

• Kerberos -h host name option for the Virtual IP address

• -K host option for server.example.com

For example:

$ vsql -h <virtual IP> -K server.example.com

You connect to Vertica using an IP address... but there is no host name to construct the Kerberos principal name.

Provide the instance or host name for the Vertica as described in Inform Vertica about the Kerberos principal

The server-side KerberosHostName configuration parameter is set to a name other than the Vertica node's host name... but the client cannot determine the host name based on the host name in the connection string alone.

Reset KerberosHostName to match the name of the Vertica node's host name. For more information, see the following topics:

• ODBC DSN Parameters

• JDBC Connection Properties

• ADO.NET Connection Properties

4 - Configuring Kerberos authentication

Kerberos authentication differs from user name/password authentication. Instead of authenticating each user to each network service, Kerberos uses symmetric encryption through a trusted third party, called the Key Distribution Center (KDC). In this environment, clients and servers validate their authenticity by obtaining a shared secret (ticket) from the KDC, after which clients and servers can talk to each other directly.

Vertica uses the GSS-API (Generic Security Services Application Programming Interface) to communicate with the Kerberos client. When you create an authentication method, specify that Vertica use the 'gss' method to authenticate with Kerberos, as in the following syntax:

=> CREATE AUTHENTICATION <method_name> METHOD 'gss' HOST <ip_address>;

Topics in this section describe how to configure the Vertica server and clients for Kerberos authentication. This section does not describe how to install, configure, or administer a Key Distribution Center.

To install the Kerberos 5 GSS-API distribution for your operating system, see the MIT Kerberos Distribution page.

You must meet the following minimum requirements to use Kerberos authentication with the Vertica server and client drivers.

Kerberos server

Your network administrator should have already installed and configured one or more Kerberos Key Distribution Centers (KDC), and the KDC must be accessible from every node in your Vertica cluster.

The KDC must support Kerberos 5 via GSSAPI. For details, see the MIT Kerberos Distribution page.

Client package

The Kerberos 5 client package contains software that communicates with the KDC server. This package is not included as part of the Vertica installation. If the Kerberos 5 client package is not present on your system, you must download and install it on all clients and servers involved in Kerberos authentication (for example, each Vertica and each Vertica client), with the exception of the KDC itself.

Kerberos software is built into Microsoft Windows. If you are using another operating system, you must obtain and install the client package.

Refer to the Kerberos documentation for installation instructions, such as on the MIT website, including the MIT Kerberos Distribution page.

Client/Server identity

Each client (users or applications that will connect to Vertica) and the Vertica server must be configured as Kerberos principals. These principals authenticate using the KDC.

Each client platform has a different security framework, so the steps required to configure and authenticate against Kerberos differ among clients. See the following topics for more information:

• Configure Vertica for Kerberos authentication
• Configure clients for Kerberos authentication

    <ul>
        <li><a href="ConfigureVerticaForKerberosAuthentication.htm"><MadCap:xref href="ConfigureVerticaForKerberosAuthentication.htm">Configure  for Kerberos Authentication</MadCap:xref></a>
        </li>
        <li><a href="ConfigureClientsForKerberosAuthentication.htm"><MadCap:xref href="ConfigureClientsForKerberosAuthentication.htm">Configure Clients for Kerberos Authentication</MadCap:xref></a>
        </li>
    </ul>