This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Kerberos authentication

Kerberos authentication uses the following components to perform user authentication.

Kerberos authentication uses the following components to perform user authentication.

Client package

The Kerberos 5 client package communicates with the KDC server. This package is not included as part of the Vertica Analytics Platform installation. Kerberos software is built into Microsoft Windows. If you are using another operating system, you must obtain and install the client package.

If you do not already have the Kerberos 5 client package on your system, download it from the MIT Kerberos Distribution page. Install the package on each Vertica server and client used in Kerberos authentication, except the KDC itself.

Refer to the Kerberos documentation for installation instructions.

Service principals

A service principal consists of a host name, a service name, and a realm to which a set of credentials gets assigned (service/hostname@REALM). These credentials connect to the service, which is a host that you connect to over your network and authenticate using the KDC.

See Specify KDC information and configure realms to create the realm name. The host name must match the value supplied by the operating system. Typically this is the fully qualified host name. If the host name part of your principal does not match the value supplied by the operating system, Kerberos authentication fails.

Some systems use a hosts file (/etc/hosts or /etc/hostnames) to define host names. A hosts file can define more than one name for a host. The operating system supplies the first entry, so use that in your principal. For example, if your hosts file contains:

192.168.1.101 v_vmart_node0001.example.com v_vmart_node0001

then use v_vmart_node0001.example.com as the hostname value.

Configure the following as Kerberos principals:

  • Each client (users or applications that connects to Vertica)

  • The Vertica server

See the following topics for more information:

Keytab files

Principals are stored in encrypted keytab files. The keytab file contains the credentials for the Vertica principal. The keytab allows the Vertica server to authenticate itself to the KDC. You need the keytab so that Vertica Analytic Database does not have to prompt for a password.

Create one service principal for each node in your cluster. You can then either create individual keytab files (one for each node containing only that node's principal) or create one keytab file containing all the principals.

  • Create one keytab file with all principals to simplify setup: all nodes have the same file, making initial setup easier. If you add nodes later you either update (and redistribute) the global keytab file or make separate keytabs for the new nodes. If a principal is compromised it is compromised on all nodes where it is present in a keytab file.

  • Create separate keytab files on each node to simplify maintenance. Initial setup is more involved as you must create a different file on each node, but no principals are shared across nodes. If you add nodes later you create keytabs on the new nodes. Each node's ke ytab contains only one principal, the one to use for that node.

Ticket-granting ticket

The Ticket-Granting Ticket (TGT) retrieves service tickets that authenticates users to servers in the domain. Future login requests use the cached HTTP Service Ticket for authentication, unless it has expired as set in the ticket_lifetime parameter in krb5.conf.

Multi-realm support

Vertica provides multi-realm support for Kerberos authentication using the SET param=value parameter in ALTER AUTHENTICATION with REALM as the parameter:

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

This allows you to assign a different realm so that users from another realm can authenticate to Vertica.

Mutli-realm support applies to GSS authentication types only. You can have one realm per authentication method. If you have multiple authentication methods, each can have its own realm:

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

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.

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
    

    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.

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.

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

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.

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

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

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.

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:

In this section

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.

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.

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

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

The Vertica client drivers support the Windows SSPI library for Kerberos authentication.

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 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 @ 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

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:

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

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.

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

3 - Troubleshooting Kerberos authentication

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

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: