Security and Authentication

Transcription

1 HPE Vertica Analytic Database Software Version: 7.2.x Document Release Date: 10/10/2017

2 Legal Notices Warranty The only warranties for Hewlett Packard Enterprise products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HPE shall not be liable for technical or editorial errors or omissions contained herein. The information contained herein is subject to change without notice. Restricted Rights Legend Confidential computer software. Valid license from HPE required for possession, use or copying. Consistent with FAR and , Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license. Copyright Notice Copyright Hewlett Packard Enterprise Development LP Trademark Notices Adobe is a trademark of Adobe Systems Incorporated. Apache Hadoop and Hadoop are either registered trademarks or trademarks of the Apache Software Foundation in the United States and/or other countries. Microsoft and Windows are U.S. registered trademarks of Microsoft Corporation. UNIX is a registered trademark of The Open Group. This product includes an interface of the 'zlib' general purpose compression library, which is Copyright Jean-loup Gailly and Mark Adler. HPE Vertica Analytic Database (7.2.x) Page 2 of 101

3 Contents Implementing Client Authentication 6 How Client Authentication Works 6 IPv4 and IPv6 for Client Authentication 7 Supported Client Authentication Methods 8 Local and Host Authentication 9 DBADMIN Authentication Access 10 Creating Authentication Records 11 Modifying Authentication Records 13 Rename an Authentication Method 13 Specify a Priority for an Authentication Method 13 Change a Parameter 13 Change the Associated Method 14 Using the Administration Tools 14 Using the Client Authentication Configuration Parameter 14 Deleting Authentication Records 15 Priorities for Client Authentication Methods 16 DBADMIN and Authentication Priority 18 Viewing Information About Client Authentication Records 18 Enabling and Disabling Authentication Methods 19 Granting and Revoking Authentication Methods 19 Hash Authentication 20 Hash Authentication Parameters 21 How to Configure Hash Authentication 22 Upgrade Considerations for Hash Authentication 23 Upgrade the Client and Server 23 Change Existing Users to SHA-512 Hash Algorithm 24 Passwords 24 About Password Creation and Modification 24 Default Password Authentication 25 Profiles 25 Create and Modify Profiles 26 Password Guidelines 27 Password Expiration 27 Set Password Expiration and Grace Period 27 Expire a Password 28 Account Locking 28 Unlock a Locked Account 28 Ident Authentication 28 Installing and Setting Up an Ident Server 30 Configuring Ident Authentication for Database Users 32 Kerberos Authentication 32 Keytab Files 34 Configure Vertica for Kerberos Authentication 34 HPE Vertica Analytic Database (7.2.x) Page 3 of 101

4 Create the Vertica Principals and Keytabs on Linux KDC 35 Creating the Principals and Keytab on Active Directory 36 Get the Kerberos Ticket and Authenticate Vertica 40 Configure Clients for Kerberos Authentication 40 Configure ODBC and vsql Clients on Non-Windows Platforms 41 Acquire an ODBC Authentication Request and Connection 42 Acquire a vsql Authentication Request Connection 43 Verify the Authentication Method 43 Configure ADO.NET, ODBC, and vsql Clients on Windows 44 Windows KDC on Active Directory with Windows Built-in Kerberos Client and Vertica 44 Linux KDC with Windows Built-in Kerberos Client and Vertica 44 Configure Windows Clients for Kerberos Authentication 45 Authenticate and Connect Clients 45 Verify an ADO.NET Authentication Request and Connection 45 Verify a vsql Authentication Request and Connection 45 Configure JDBC Clients on All Platforms 46 Create a JDBC Login Context 47 Troubleshooting Kerberos Authentication 49 JDBC Client Authentication Fails 49 Working Domain Name Service (DNS) Not Configured 49 System Clocks Out of Sync 49 All Systems Except Red Hat 7/CentOS 7 49 Red Hat 7/CentOS 7 Systems 50 Clock Skew on Linux Virtual Machines 50 Kerberos Ticket Is Valid, But Hadoop Access Fails 50 Encryption Algorithm Choices 51 Kerberos Passwords Not Recognized 51 Using the ODBC Data Source Configuration Utility 51 Authentication Failure in Backup, Restore, or Admin Tools 51 Server's Principal Name Does Not Match Host Name 52 Principal/Host Mismatch Issues and Resolutions 52 Rename the KerberosHostName 54 LDAP Authentication 55 LDAP Prerequisites and Definitions 55 LDAP Parameters 57 LDAP Bind Parameters 58 LDAP Search and Bind Parameters 59 Using LDAP Over SSL/TLS 59 Configuring Multiple LDAP Servers 61 LDAP Bind Methods 62 LDAP Anonymous Binding 62 Workflow for Configuring LDAP Bind 62 Workflow for Configuring LDAP Search and Bind 64 LDAP Link Service 65 Automatic Synchronization 65 Enable LDAP Link 66 Using LDAP Link 68 HPE Vertica Analytic Database (7.2.x) Page 4 of 101

5 LDAP Link Parameters 70 Troubleshooting LDAP Link Issues 75 Disconnected (Orphaned) Users and Roles 75 User Conflicts 76 TLS/SSL Server Authentication 77 Certificate Authority 78 Public and Private Keys 78 SSLAuthentication 79 SSL Authentication 79 Certificate Authority 80 Public and Private Keys 80 SSL Overview 80 Set Up SSL Server Authentication and SSL Encryption 81 Set SSL Server for Mutual Mode Authentication 82 Generating SSL Certificates and Keys 82 Create a Certificate Authority Private Key and Public Certificate 83 Generating Certificates and Keys for MC 84 Create a Certificate and Submit it for Signing 84 Self-Sign a Certificate for Testing 85 Importing a New Certificate to MC 86 Configuring SSL 86 Configuring SSL for ODBC Clients 87 Set SSLMode Connection Property 88 Enable SSL Mutual Mode Authentication 88 Configuring SSL for JDBC Clients 89 Set Required Properties 89 Run the SSL Debug Utility 89 Distributing Certificates and Keys 90 TLS Authentication 91 Implementing Client Self-Authentication 92 Connector Framework Service 93 Document Metadata 94 Security Key and Authorization Functions 94 SQL Statement and Security Parameter 94 CFS Configuration File 95 Implementing CFS 95 Modify the CFS Configuration File 95 Create a View 96 Install the Security Key 97 Verify CFS implementation success 97 Query the HPE IDOL Data 98 System Table Restriction 98 Privileges 99 Determine if a Table is Restricted 99 Show Accessible System Tables 100 HPE Vertica Analytic Database (7.2.x) Page 5 of 101

6 Send Documentation Feedback 101 Implementing Client Authentication Vertica restricts which database users can connect through client authentication. The database server uses client authentication to establish the identity of the requesting client and determines whether that client is authorized to connect to the Vertica server using the supplied credentials. When a user or client application connect to the Vertica database server, it supplies a unique user name and password to gain access. Vertica offers several client authentication methods. You can configure Vertica to require just a user name for connections, you likely require more secure means of authentication, such as a password at a minimum. Note: Topics in this section describe authentication methods supported at the database server layer. For information on authentication between server and client, see TLS/SSL Server Authentication. How Client Authentication Works When connecting to a Vertica database, a user or client application must supply the name of a valid user account. In addition, the application usually includes a means of authentication, such as a password or security certificate. There are two types of client authentication: LOCAL Authenticating users or applications that are trying to connect from the same node that the database is running on. HOST Authenticating users or applications that are trying to connect from a node that has a different IPv4 or IPv6 address than the database. The DBADMIN user manages the client authentication information that the database uses to authenticate users. Vertica takes the following steps to authenticate users: 1. When a user or application attempts to connect to a Vertica database, the system checks to see if the user is a DBADMIN user. If so, authentication occurs using the assigned authentication method, local trust or local hash authentication. HPE Vertica Analytic Database (7.2.x) Page 6 of 101

7 2. For non-dbadmin users, the database checks to see if the user is associated with an authentication method through a GRANT statement. If so, the database allows the user to log in if they match the parameters required for that authentication method. Note: For detailed information on how authentication priorities work, see Priorities for Client Authentication Methods. The DBADMIN user can grant an authentication method to users or user roles. The DBADMIN user can also create a default authentication method that Vertica uses when no authentication has been associated with a user or role. 3. If the user has not been granted an authentication method, the database checks to see if the DBADMIN has established a default authentication method. 4. If the DBADMIN has specified a default authentication method, the database authenticates the user using that default method. 5. If you have not specified a default authentication method, the database checks to see if the DBADMIN user has defined any authentication methods. If not, no authentication information exists in the database. However, if a password exists, the DBADMIN user can log in. 6. If authentication information exists, Vertica rejects the user request to connect to the database. The DBADMIN has not granted an authentication method for that user nor has the DBADMIN defined a default authentication method for all users ('public'). 7. If authentication records exist in the database, Vertica uses implicit trust/implicit password to authenticate the user. IPv4 and IPv6 for Client Authentication Vertica supports clients using either the IPv4 or the IPv6 protocol to connect to the database server. Internal communication between database servers must consistently use one address family (IPv4 or IPv6). The client, however, can connect to the database from either type of IP address. If the client will be connecting from either IPv4 or IPv6, you must create two authentication methods, one for each address. Any authentication method that uses HOST authentication requires an IP address. For example, the first statement allows users to connect from any IPv4 address. The second statement allows users to connect from any IPv6 address: => CREATE AUTHENTICATION <name> METHOD 'gss' HOST ' /0; --IPv4 HPE Vertica Analytic Database (7.2.x) Page 7 of 101

8 => CREATE AUTHENTICATION <name> METHOD 'gss' HOST '::/0; --IPv6 If you are using a literal IPv6 address in a URL, you must enclose the IPv6 address in square brackets as shown in the following examples: => ALTER AUTHENTICATION Ldap SET host='ldap://[1dfa:2bfa:3:45:5:6:7:877]'; => ALTER AUTHENTICATION Ldap SET host='ldap://[fdfb:dbfa:0:65::177]'; => ALTER AUTHENTICATION Ldap SET host='ldap://[fdfb::177]'; => ALTER AUTHENTICATION Ldap SET host='ldap://[::1]'; => ALTER AUTHENTICATION Ldap SET host='ldap://[1dfa:2bfa:3:45:5:6:7:877]:5678'; If you are working with a multi-node cluster, any IP/netmask settings in (HOST, HOST TLS, HOST NO TLS) must match all nodes in the cluster. This setup allows the database owner to authenticate with and administer every node in the cluster. For example, specifying /30 allows a CIDR address range of For detailed information about IPv6 addresses, see RFC 1924 and RFC Supported Client Authentication Methods Vertica supports the following types of authentication to prove a client's identity. Trust Authorizes any user that connects to the database using a valid user name, no password is required and authentication is not performed. Reject Rejects the connection attempt when a user with an invalid user name attempts to connect to the database. Kerberos (GSS) Authorizes connecting to the database using a MIT Kerberos implementation. The KDC must support Kerberos 5 using GSS-API. This API also provides compatibility with non-mit Kerberos implementations, such as Java and Windows clients. Hash Sends encrypted passwords hashed by the MD5 algorithm or the more secure SHA-512 method over the network. The server provides the client with salt. LDAP Works like password authentication except the LDAP method authenticates the client against a Lightweight Directory Access Protocol or Active Directory server. Ident Authenticates the client against the username in an Ident server. HPE Vertica Analytic Database (7.2.x) Page 8 of 101

9 TLS authentication Authenticates the client using digital certificates that contain a public key. Transport Layer Security (TLS) is the successor to Secure Sockets Layer (SSL) authentication. Local and Host Authentication You can define a client authentication method as: Local: Local connection to the database. Host: Remote connection to the database from different hosts, each with their own IPv4 or IPv6 address and host parameters. For more information see IPv4 and IPv6 for Client Authentication above. Some authentication methods cannot be designated as local, as listed in this table: Authentication Method Local? Host? Kerberos (GSS) No Yes Ident Yes No LDAP Yes Yes Hash Yes Yes Reject Yes Yes Trust Yes Yes Authentication for Chained Users and Roles Vertica supports creating chained users and roles, where you can grant ROLE2 privileges to ROLE1. All users in ROLE1 use the same authentication assigned to ROLE2. For example: => CREATE USER user1; => CREATE ROLE role1; => CREATE ROLE role2; => CREATE AUTHENTICATION h1 method 'hash' local; => GRANT AUTHENTICATION h1 to role2; => GRANT role2 to role1; HPE Vertica Analytic Database (7.2.x) Page 9 of 101

10 => GRANT role1 to user1; The user and role chain in the example above can be illustrated as follows: auth1 -> role2 -> role1 -> user1 In this example, since role2 privileges are granted to role1 you only need to grant authentication to role2 to also enable it for role1. DBADMIN Authentication Access The DBADMIN user must have access to the database at all times. The DBADMIN account must authenticate against the database using local trust or local hash authentication. Hewlett Packard Enterprise recommends that you create an authentication method (LOCAL TRUST or LOCAL PASSWORD) with a very high priority, say, 10,000. Grant this method to the DBADMIN user and set the priority using ALTER AUTHENTICATION. With the high priority, this new authentication method supersedes any authentication methods you create for PUBLIC (which includes the DBADMIN user). Even if you make changes to PUBLIC authentication methods, the DBADMIN user can now connect to the database at any time. This example shows how you configure local trust authentication for the DBADMIN user. As a result, the user can use vsql with the -h option and does not need to enter a password: => CREATE AUTHENTICATION v_dbadmin_trust METHOD 'trust' LOCAL; => GRANT AUTHENTICATION v_dbadmin_trust TO dbadmin; => ALTER AUTHENTICATION v_dbadmin_trust PRIORITY 10000; The next example shows how you configure local hash authentication for DBADMIN. They allow the user to access the Vertica database using the assigned password from any IPv4 address. The DBADMIN user can access the database using vsql -h Hostname --host Hostname, the Administration Tools, or any other tools that connects to Vertica: => CREATE AUTHENTICATION v_dbadmin_hash METHOD 'hash' HOST ' /0'; => GRANT AUTHENTICATION v_dbadmin_hash TO dbadmin; => ALTER AUTHENTICATION v_dbadmin_hash PRIORITY 10000; => SELECT SET_CONFIG_PARAMETER('SecurityAlgorithm', 'SHA512'); Note: Vertica supports IPv4 and IPv6 addresses. For more information, see IPv4 and IPv6 for Client Authentication. HPE Vertica Analytic Database (7.2.x) Page 10 of 101

11 Creating Authentication Records You can manage client authentication records using vsql commands. To use these statements, you must be connected to the database. Important: You cannot modify client authentication records using the Administration Tools. The Administration Tools interface allows you to modify the contents of the vertica.conf file. However, Vertica ignores any client authentication information stored in that file. When you create authentication records using CREATE AUTHENTICATION, specify the following information. What you need to specify Authentication method name Authentication type Description A name that you define for Vertica use. The type of authentication Vertica should use to validate the user or client attempting to connect: 'gss' 'ident' 'ldap' 'hash' 'reject' 'trust' 'tls' Access method LOCAL HOST HOST NO TLS HOST TLS Host IP address or range of IP addresses from which the user or HPE Vertica Analytic Database (7.2.x) Page 11 of 101

12 What you need to specify IP address Description application tries to connect. This can be an IPv4 address or an IPv6 address. For more information, see IPv4 and IPv6 for Client Authentication. The following examples show how to create authentication records that are stored in the catalog. When you create an authentication record using CREATE AUTHENTICATION, Vertica automatically enables it. This example shows you how to create an authentication method named localpwd to authenticate users who are trying to log in from a local host using a password: => CREATE AUTHENTICATION localpwd METHOD 'hash' LOCAL; This example shows you how to create an authentication method named v_ldap that uses LDAP over TLS to authenticate users logging in from the host with the IPv4 address /23: => CREATE AUTHENTICATION v_ldap METHOD 'ldap' HOST TLS ' /23'; This example shows you how to create an authentication method named v_kerberos to authenticate users that are trying to connect from any host in the networks 2001:0db8:0001:12xx: => CREATE AUTHENTICATION v_kerberos METHOD 'gss' HOST '2001:db8:1::1200/56'; This example shows you how to create an authentication method named, RejectNoSSL, that rejects users from any IP address that are trying to authenticate without SSL/TLS: => CREATE AUTHENTICATION RejectNoSSL METHOD 'reject' HOST NO TLS ' /0'; --IPv4 => CREATE AUTHENTICATION RejectNoSSL METHOD 'reject' HOST NO TLS '::/128'; --IPv6 See Also Deleting Authentication Records Enabling and Disabling Authentication Methods Granting and Revoking Authentication Methods Modifying Authentication Records HPE Vertica Analytic Database (7.2.x) Page 12 of 101

13 Modifying Authentication Records To modify existing authentication records, you must first be connected to your database. The following examples show how to make changes to your authentication records. For more information see ALTER AUTHENTICATION. Rename an Authentication Method Rename the v_kerberos authentication method to K5, and enable it. All users who have been associated with the v_kerberos authentication method are now associated with the K5 method granted instead. => ALTER AUTHENTICATION v_kerberos RENAME TO K5 ENABLE; Specify a Priority for an Authentication Method Specify a priority of 10 for K5 authentication: => ALTER AUTHENTICATION K5 PRIORITY 10; For more information see Priorities for Client Authentication Methods. Change a Parameter Set the system_users parameter for ident1 authentication to root: => CREATE AUTHENTICATION ident1 METHOD 'ident' LOCAL; => ALTER AUTHENTICATION ident1 SET system_users='root'; Change the IP address and specify the parameters for an LDAP authentication method named Ldap1. In this example, you specify the bind parameters for the LDAP server. Vertica connects to the LDAP server, which authenticates the Vertica client. If the authentication succeeds, Vertica authenticates any users who have been granted the Ldap1 authentication method on the designated LDAP server: => CREATE AUTHENTICATION Ldap1 METHOD 'ldap' HOST ' '; => ALTER AUTHENTICATION Ldap1 SET host='ldap:// ', binddn_prefix='cn=', binddn_suffix=',dc=qa_domain,dc=com'; Change the IP address, and specify the parameters for an LDAP authentication method named Ldap1. Assume that Vertica does not have enough information to create the HPE Vertica Analytic Database (7.2.x) Page 13 of 101

14 distinguished name (DN) for a user attempting to authenticate. Therefore, in this case, you must specify to use LDAP search and bind: => CREATE AUTHENTICATION LDAP1 METHOD 'ldap' HOST ' '; => ALTER AUTHENTICATION Ldap1 SET host='ldap:// ', basedn='dc=qa_domain,dc=com',binddn='cn=manager,dc=qa_domain, dc=com',search_attribute='cn',bind_password='secret'; Change the Associated Method Change the localpwd authentication from trust to hash: => CREATE AUTHENTICATION localpwd METHOD 'trust' LOCAL; => ALTER AUTHENTICATION localpwd METHOD 'hash'; ALTER AUTHENTICATION validates the parameters you enter. If there are errors, it disables the authentication method that you are trying to modify. Using the Administration Tools The advantages of using the Administration Tools are: You do not have to connect to the database The editor verifies that records are correctly formed The editor maintains records so they are available to you to edit later Note: You must restart the database to implement your changes. For information about using the Administration Tools to create and edit authentication records, see Creating Authentication Records. Using the Client Authentication Configuration Parameter The advantage of using the ClientAuthentication configuration parameter is that the changes are implemented immediately across all nodes within the database cluster. You do not need to restart the database. However, all the database nodes must be up and you must connect to the database before you set this parameter. Most importantly, this method does not verify that records are correctly formed and it does not maintain the records so you can modify them later. New authentication records are appended to the list of existing authentication records. Because Vertica scans the list of records from top to bottom and uses the first record that HPE Vertica Analytic Database (7.2.x) Page 14 of 101

15 matches the incoming connection, you might find your newly-added record does not have an effect if Vertica used an earlier record instead. To configure client authentication through a connection parameter, use the ALTER DATABASE statement: => ALTER DATABASE exampledb SET ClientAuthentication = 'connection type user name address method'; When you specify authentication records, make sure to adhere to the following guidelines: Fields that make up the record can be separated by white space or tabs Other than IP addresses and mask columns, field values cannot contain white space Examples The following example creates an authentication record for the trust method: => ALTER DATABASE exampledb SET ClientAuthentication = 'hostnossl dbadmin /0 trust'; The following example creates an authentication record for the LDAP method: => ALTER DATABASE exampledb SET ClientAuthentication = 'host all /8 ldap "ldap://summit.vertica.com;cn=;,dc=vertica,dc=com"'; The following example specifies three authentication records. In a single command, separate each authentication record by a comma: => ALTER DATABASE exampledb SET ClientAuthentication = 'hostnossl dbadmin /0 trust, hostnossl all /0 md5, local all trust'; Deleting Authentication Records To delete client authentication record, use DROP AUTHENTICATION. To use this approach, you have to be connected to your database. To delete an authentication record for md5_auth use the following command: => DROP AUTHENTICATION md5_auth; To delete an authentication record for a method that has been granted to a user, use the CASCADE keyword: => CREATE AUTHENTICATION localpwd METHOD 'password' LOCAL; => GRANT AUTHENTICATION localpwd TO jsmith; => DROP AUTHENTICATION localpwd CASCADE; HPE Vertica Analytic Database (7.2.x) Page 15 of 101

16 See Also Creating Authentication Records Granting and Revoking Authentication Methods Priorities for Client Authentication Methods You can associate one or more authentication methods to a connection or user. For a user who has multiple authentication methods, specify the order in which Vertica should try them. To do so, assign a priority to each authentication method using ALTER AUTHENTICATION. All priority values should be a non-negative INTEGER. Higher values indicate higher priorities. Vertica tries to authenticate a user with an authentication method in order of priority from highest to lowest. For example: A priority of 10 is higher than a priority of 5. A priority 0 is the lowest possible value. Priority Order for Authentication Methods When you associate multiple authentication methods with a connection, Vertica uses the following order to determine how to authenticate the client: Administrator-assigned priority for an individual method The most specific IP addresses have priority over the least specific IP addresses For example, the IPv4 address /25 has priority over /24, which in turn has priority over /16. The IPv6 address 2001:db8:ab::123/128 has priority over 2001:db8:1::1200/56. Reject GSS LDAP Ident Hash Trust Authentication Attempts Using Multiple Methods If there is only one authentication method associated with a user, Vertica uses that method to authenticate the login attempt. HPE Vertica Analytic Database (7.2.x) Page 16 of 101

17 If the administrator has associated multiple authentication methods with a given user or IP address, Vertica tries to authenticate as follows: If the highest priority authentication method is Ident and authentication fails, Vertica tries the next highest priority authentication method, regardless of what method it uses. If the next attempt does not use Ident authentication and fails, the authentication process ends. However, if the next attempt uses Ident and fails, Vertica continues to the next highest priority method. This process continues until authentication is successful or a non-ident authentication attempt fails. If the highest priority method is LDAP and authentication fails, Vertica searches for the next highest priority LDAP method. Authentication attempts continue until the authentication is successful, or there are no additional LDAP authentication methods that satisfy the connection criteria. Note that if a user not found error occurs during LDAP authentication, the retry connection attempt initiates only if you set the ldap_continue parameter to yes. For all other authentication types, Vertica tries the highest priority authentication method associated with that user. If that authentication fails, the authentication process stops. For example, suppose there are two client authentication methods associated with a user, as follows: => CREATE AUTHENTICATION auth_name1 METHOD 'hash' LOCAL; => GRANT AUTHENTICATION auth_name1 to user; => ALTER AUTHENTICATION auth_name1 PRIORITY 5; => CREATE AUTHENTICATION auth_name2 METHOD 'ident' LOCAL; => GRANT AUTHENTICATION auth_name2 to user; => ALTER AUTHENTICATION auth_name2 PRIORITY 10; When user tries to connect to the database, Vertica first tries auth_name2 to authenticate because it has a higher priority. If that fails, Vertica tries auth_name1. If that fails, authentication fails. Specifying Authentication Method Priority To specify priorities for client authentication methods, use ALTER AUTHENTICATION. The priority value must be a non-negative INTEGER. Higher numbers indicate a higher priority. The default value, 0, is the lowest possible priority. The syntax is: ALTER AUTHENTICATION <name>... PRIORITY <priority_value>; HPE Vertica Analytic Database (7.2.x) Page 17 of 101

18 If you do not specify a priority, or omit the <priority_value> when using ALTER AUTHENTICATION, Vertica sets the priority to 0. DBADMIN and Authentication Priority To allow the DBADMIN user to connect to the database at any time, Hewlett Packard Enterprise recommends that you create an authentication method (LOCAL TRUST or LOCAL PASSWORD) with a very high priority, such as 10,000. Grant this method to the DBADMIN user, and set the priority using ALTER AUTHENTICATION. With the high priority, this new authentication method supersedes any authentication methods you create for PUBLIC (which includes the DBADMIN user). Even if you make changes to PUBLIC authentication methods, the DBADMIN still has access. Note: For the DBADMIN user to be able to perform all Admintools functions, the DBADMIN must always be able to authenticate by LOCAL TRUST or LOCAL PASSWORD (the default for DBADMIN user). If you have changed DBADMIN user authentication from LOCAL TRUST or LOCAL PASSWORD, use the ALTER AUTHENTICATION statement to once again give the DBADMIN user LOCAL TRUST or LOCAL PASSWORD authentication. Viewing Information About Client Authentication Records For information about client authentication records that you have configured for your database, query the following system tables in the V_CATALOG schema: CLIENT_AUTH CLIENT_AUTH_PARAMS PASSWORD_AUDITOR USER_CLIENT_AUTH To determine the details behind the client authentication used for a particular user session, query the following tables in the V_MONITOR schema: SESSIONS USER_SESSIONS HPE Vertica Analytic Database (7.2.x) Page 18 of 101

19 Enabling and Disabling Authentication Methods When you create an authentication method, Vertica stores it in the catalog and enables it automatically. To enable or disable an authentication method, use the ALTER AUTHENTICATION statement. To use this approach, you must be connected to your database. If an authentication method has not been enabled, Vertica cannot use it to authenticate users and clients trying to connect to the database. To enable an authentication method: ALTER AUTHENTICATION v_kerberos ENABLE; To disable this authentication method: ALTER AUTHENTICATION v_kerberos DISABLE; See Also Creating Authentication Records Deleting Authentication Records Granting and Revoking Authentication Methods Modifying Authentication Records Granting and Revoking Authentication Methods Before Vertica can validate a user or client through an authentication method, you must first associate that authentication method with the user or role that requires it. To do this, use GRANT AUTHENTICATION. When that user or role no longer needs to connect to Vertica using that method, you can disassociate that authentication from that user with REVOKE AUTHENTICATION. Grant Authentication Methods You can grant an authentication method to a specific user or role. You can also specify the default authentication method by granting an authentication method to Public. Use the GRANT (Authentication) statement as follows: HPE Vertica Analytic Database (7.2.x) Page 19 of 101

20 This example uses a GRANT AUTHENTICATION statement to associate v_ldap authentication with user jsmith: => GRANT AUTHENTICATION v_ldap TO jsmith; This example uses a GRANT AUTHENTICATION statement to associate v_gss authentication to the role DBprogrammer: => CREATE ROLE DBprogrammer; => GRANT AUTHENTICATION v_gss to DBprogrammer; This example sets the default client authentication method to v_localpwd: => GRANT AUTHENTICATION v_localpwd TO Public; Revoke Authentication Methods If you no longer want to authenticate a user or client with a given authentication method, use the REVOKE (Authentication) statement as follows: This example revokes v_ldap authentication from user jsmith: => REVOKE AUTHENTICATION v_ldap FROM jsmith; This example revokes v_gss authentication from the role DBprogrammer: => REVOKE AUTHENTICATION v_gss FROM DBprogrammer; This example removes localpwd as the default client authentication method: => REVOKE AUTHENTICATION localpwd from Public; Hash Authentication Vertica provides a hash authentication method that allows you to use the MD5 algorithm or the more secure algorithm, SHA-512, to store user passwords. SHA-512 is one of the industry-standard SHA-2 family of hash algorithms that address weaknesses in SHA-1 and MD5. For information on creating passwords to be hashed during authentication see Passwords Note: Hewlett Packard Enterprise strongly recommends that you use SHA-512 for hash authentication because it is more secure than MD5. Before Vertica 7.1, the database used only MD5 to store passwords. The MD5 algorithm continues to be the default algorithm for storing passwords after you update your Vertica HPE Vertica Analytic Database (7.2.x) Page 20 of 101

21 pre-7.1 server. All current users can still authenticate as in earlier releases until you reconfigure hash authentication. Before you perform hash authentication, review the following topics: Hash Authentication Parameters Describes the two hash authentication parameters that specify which hashing algorithm to use. Upgrade Considerations for Hash Authentication Before you implement the SHA- 512 algorithm for one or more users, you must be aware of several issues. For details, review this topic before proceeding. How to Configure Hash Authentication After you decide to implement hash authentication in your database, follow the steps described in this topic.. Hash Authentication Parameters Two parameters control which algorithm hash authentication uses for hashing and storing user passwords: A user-level parameter, Security_Algorithm: => ALTER USER username SECURITY_ALGORITHM 'MD5' IDENTIFIED BY 'newpassword'; => ALTER USER username SECURITY_ALGORITHM 'SHA512' IDENTIFIED BY 'newpassword'; A system-level configuration parameter, SecurityAlgorithm: => SELECT SET_CONFIG_PARAMETER('SecurityAlgorithm', 'MD5'); => SELECT SET_CONFIG_PARAMETER('SecurityAlgorithm', 'SHA512'); Both parameters can have the following values: 'NONE' 'MD5' 'SHA512' The user-level parameter usually has precedence over the system-level parameter. However, if the user-level parameter is 'NONE', Vertica hashes passwords with the algorithm assigned to the system-level parameter value. If both parameters are 'NONE', Vertica uses the MD5 algorithm. These values, which are stored in the PASSWORD_AUDITOR system table, affect the security algorithm that is actually used for hash authentication. HPE Vertica Analytic Database (7.2.x) Page 21 of 101

22 User-Level Parameter Value System-Level Parameter Value Algorithm Used for Hash Authentication 'NONE' 'NONE' MD5 'NONE' 'MD5' MD5 'NONE' 'SHA512' SHA-512 'MD5' 'NONE' MD5 'MD5' 'MD5' MD5 'MD5' 'SHA512' MD5 'SHA512' 'NONE' SHA-512 'SHA512' 'MD5' SHA-512 'SHA512' 'SHA512' SHA-512 How to Configure Hash Authentication Follow these steps to configure hash authentication: 1. Create an authentication method that is based on hash encryption. When you create an authentication method, it is automatically enabled for use. The following example shows how to create an authentication method v_hash for users logging in from the IP address /0. => CREATE AUTHENTICATION v_hash METHOD 'hash' HOST ' /0'; If users are trying to connect from an IPv6 address, the statement might look like this example: => CREATE AUTHENTICATION v_hash METHOD 'hash' HOST '2001:db8:ab::123/128'; 2. Decide which password-hashing algorithm you want to use: MD5 or the more secure SHA Specify the security algorithm as follows: HPE Vertica Analytic Database (7.2.x) Page 22 of 101

23 At the system level, set the SecurityAlgorithm configuration parameter. This setting applies to all users, unless their user-level security is set to another value: => ALTER DATABASE mydb SecurityAlgorithm = 'MD5'; => ALTER DATABASE mydb SecurityAlgorithm = 'SHA512'; If you want users to inherit the system-level security, set their passwords to expire immediately. Users must change their passwords before they log in again. Alternatively, you can ask users to change their passwords. Vertica hashes all new passwords using the system-level security algorithm. At the user level, use ALTER USER to set the Security_Algorithm user parameter. Changing this parameter at the user level overrides the system-level value: => ALTER USER username SECURITY_ALGORITHM 'MD5' IDENTIFIED BY 'newpassword'; => ALTER USER username SECURITY_ALGORITHM 'SHA512' IDENTIFIED BY 'newpassword'; 4. Associate the v_hash authentication method with the desired users or user roles, using a GRANT statement: => GRANT AUTHENTICATION v_hash to user1, user2,...; For more information about how these parameters work, see Hash Authentication Parameters. Upgrade Considerations for Hash Authentication For Vertica releases before 7.1, MD5 is the only algorithm used for hashing passwords. In Vertica 7.1, you can use either the MD5 algorithm or the more secure SHA-512 algorithm. Before you upgrade, you must consider the following behaviors to avoid problems. Upgrade the Client and Server To implement the more secure SHA-512 algorithm for hashing passwords, you must upgrade BOTH the client and the server to Vertica 7.1 or higher. If you upgrade the server but not the client and specify that one or more users store their passwords using SHA-512, the client does not understand hashing with SHA-512. When it sends a message to the server, the server returns an error. HPE Vertica Analytic Database (7.2.x) Page 23 of 101

24 Change Existing Users to SHA-512 Hash Algorithm When you upgrade from a pre-7.1 database, the user-level parameter Security_ Algorithm, is set to 'NONE'. This allows all existing users to continue connecting to the Vertica server and their passwords are hashed using MD5. If you want one or more users to use the SHA-512 algorithm, set the system-level parameter Security Algorithm to 'SHA512' and change the user passwords. Use one of three methods to change the user password: Manually set the user's user-level security algorithm to 'SHA512'. Then, change the user s password, as in the following statement: => ALTER USER username SECURITY_ALGORITHM 'SHA512' IDENTIFIED BY 'newpassword'; Set the user's password to expire immediately as in the following statement. After the password expires, the user responds by changing it. => ALTER USER username PASSWORD EXPIRE; Ask the user to change the password. All new passwords inherit the system-level security algorithm, which is SHA-512. Passwords Assign a password to a user to allow that user to connect to the database using password authentication. When the user supplies the correct password a connection to the database occurs. Vertica stores passwords in an encrypted format to prevent potential theft. However, the transmission of the password to Vertica is in plain text. Thus, it is possible for a "man-inthe-middle" attack to intercept the password. Implementing Hash Authentication ensures secure login using passwords. About Password Creation and Modification You must be a superuser to create passwords for user accounts using the CREATE USER statement. A superuser can set any user account's password. HPE Vertica Analytic Database (7.2.x) Page 24 of 101

25 To add a password, use the ALTER USER statement. To change a password, use ALTER USER or the vsql \password command. Users can also change their own passwords. To make password authentication more effective, Vertica recommends that you enforce password policies that control how often users are forced to change passwords and the required content of a password. You set these policies using Profiles. Default Password Authentication When you have not specified any authentication methods, Vertica defaults to using password authentication for user accounts that have passwords. If you create authentication methods, even for remote hosts, password authentication is disabled. In such cases, you must explicitly enable password authentication. The following commands create the local_pwd authentication method and make it the default for all users. When you create an authentication method, Vertica enables it automatically: => CREATE AUTHENTICATION local_pwd METHOD hash' LOCAL; => GRANT AUTHENTICATION local_pwd To Public; Profiles You set password policies using profiles. A profile is a group of parameters that includes requirements for user passwords. A profile controls: How often users must change their passwords. How many times users must change their passwords before they can reuse an old password. How many times a user can fail to log in before the account is locked. The required length and content of the password: Maximum and minimum number of characters Minimum number of capital letters, lowercase letters, digits, and symbols required in a password. To set a user's password policy, assign the user to a profile. To enforce different password policies for different users, create multiple profiles. For example, you might create one profile for interactive users, requiring them to frequently change their HPE Vertica Analytic Database (7.2.x) Page 25 of 101

26 passwords. You might create another profile for user accounts that are not required to change passwords. Create and Modify Profiles You create profiles using the CREATE PROFILE statement and change profiles using ALTER PROFILE. You can assign a user to a profile when you create the user (CREATE USER), or after, using the ALTER USER statement. A user can be assigned to only one profile at a time. All newly created databases contain an initial profile named DEFAULT. Vertica assigns all users to the DEFAULT profile if: You do not explicitly assign users a profile when you create them. You drop the profile to which a user is currently assigned. You can change the policy parameters in the DEFAULT profile, but you cannot delete it. Important: During upgrades from versions of Vertica earlier than version 5.0, each database receives a DEFAULT profile. All users are then automatically assigned to that profile. The profiles that you create can inherit some or all of their policy parameters from the DEFAULT profile. When you create a profile using CREATE PROFILE, a parameter inherits its value from the DEFAULT profile if: You set it to the DEFAULT value. You do not assign a value. If you change a parameter in the DEFAULT profile, you also change that parameter's value in every profile that inherits the parameter from DEFAULT. Changes to a profile's policies for password content do not have an immediate effect on the users. When Vertica does not test user's passwords to verify that they comply with the new password criteria. Instead, the changed settings only affect the users the next time they change their password. To make sure that users comply with the new password policy, use the ALTER USER statement to expire user passwords. Vertica prompts users with expired passwords to change their passwords when they next log in. Note: Only the profile settings for how many failed login attempts trigger Account Locking. All password complexity, reuse, and lifetime settings affect only passwords that Vertica manages. HPE Vertica Analytic Database (7.2.x) Page 26 of 101

27 See Also PROFILES Creating a Database Name and Password Password Guidelines For passwords to be effective, they must be hard to guess. You need to protect passwords from: Dictionary-style, brute-force attacks Users who have knowledge of the password holder (family names, birth dates, etc.) Use Profiles to enforce good password practices (password length and required content). Make sure database users know the password guidelines, and encourage them not to use personal information in their passwords. For guidelines on creating strong passwords go to Microsoft Tips for Creating a Strong Password. See Also Creating a Database Name and Password Password Expiration User profiles control how often users must change their passwords. Initially, the DEFAULT profile is set so that passwords never expire. Important: Password expiration has no effect on any of the user's current sessions. Set Password Expiration and Grace Period You can change the default value to set a password expiration. Alternatively, you can create additional profiles that set time limits for passwords and assign users to them. When a password expires, the user must change the password on the next login. However, you can set a PASSWORD_GRACE_TIME in any individual user's profile, allowing that user to log in after the expiration. After the password expires, Vertica issues a warning about the password expiration but continues to recognize the password. After the grace period ends, users must change their passwords to log in, unless they have changed them already in response to the warning. HPE Vertica Analytic Database (7.2.x) Page 27 of 101

28 Expire a Password You can expire a user's password immediately using the ALTER USER statement's PASSWORD EXPIRE parameter. By expiring a password, you can: Force users to comply with a change to password policy. Set a new password when a user forgets the old password. Account Locking In a profile, you can set a password policy for how many consecutive failed login attempts a user account is allowed before locking. This locking mechanism helps prevent dictionary-style brute-force attempts to guess users' passwords. Set Account Locking Set this value using the FAILED_LOGIN_ATTEMPTS parameter using the CREATE PROFILE or ALTER PROFILE statement. Vertica locks any user account that has more consecutive failed login attempts than the value to which you set FAILED_LOGIN_ATTEMPTS. The user cannot log in to a locked account, even by supplying the correct password. Unlock a Locked Account You can unlock accounts in one of two ways, depending on your privileges. Manually If you are a superuser, you can manually unlock the account using the ALTER USER command. Note: A superuser account cannot be locked, because it is the only user that can unlock accounts. For this reason, choose a very secure password for a superuser account. See Password Guidelines for suggestions. Password Lock Time Setting Specify the number of days until an account unlocks in the PASSWORD_LOCK_TIME parameter of the user's profile. Vertica automatically unlocks the account after the specified number of days has passed. If you set this parameter to UNLIMITED, the user's account is never automatically unlocked, and a superuser must manually unlock it. Ident Authentication The Ident protocol, defined in RFC 1413, authenticates a database user with a system user name.to see if that system user can log in without specifying a password, you HPE Vertica Analytic Database (7.2.x) Page 28 of 101

29 configure Vertica client authentication to query an Ident server. With this feature, the DBADMIN user can run automated scripts to execute tasks on the Vertica server. Caution: Ident responses can be easily spoofed by untrusted servers. Use Ident authentication only on local connections, where the Ident server is installed on the same computer as the Vertica database server. Following the instructions in these topics to install, set up, and configure Ident authentication for your database: Installing and Setting Up an Ident Server Configuring Ident Authentication for Database Users Ident Configuration Examples The following examples show several ways to configure Ident authentication. Allow system_user1 to connect to the database as Verticavuser1: => CREATE AUTHENTICATION v_ident METHOD 'ident' LOCAL; => ALTER AUTHENTICATION v_ident SET system_users='system_user1'; => GRANT AUTHENTICATION v_ident to vuser1; => ENABLE AUTHENTICATION v_ident; Allow system_user1, system_user2, and system_user3 to connect to the database as vuser1. Use colons (:) to separate the user names: => CREATE AUTHENTICATION v_ident METHOD 'ident' LOCAL; => ALTER AUTHENTICATION v_ident SET system_users='system_user1:system_user2:system_user3'; => GRANT AUTHENTICATION v_ident TO vuser1; => ENABLE AUTHENTICATION v_ident; Associate the authentication with Public using a GRANT AUTHENTICATION statement. The users, system_user1, system_user2, and system_user3 can now connect to the database as any database user: => CREATE AUTHENTICATION v_ident METHOD 'ident' LOCAL; => ALTER AUTHENTICATION v_ident SET system_users='system_user1:system_user2:system_user3'; => GRANT AUTHENTICATION to Public; => ENABLE AUTHENTICATION v_ident; Set the system_users parameter to * to allow any system user to connect to the database as vuser1: => CREATE AUTHENTICATION v_ident METHOD 'ident' LOCAL; => ALTER AUTHENTICATION v_ident SET system_users='*'; => GRANT AUTHENTICATION v_ident TO vuser1; => ENABLE AUTHENTICATION v_ident; HPE Vertica Analytic Database (7.2.x) Page 29 of 101

30 Using a GRANT statement, associate the v_ident authentication with Public to allow system_user1 to log into the database as any database user: => CREATE AUTHENTICATION v_ident METHOD 'ident' LOCAL; => ALTER AUTHENTICATION v_ident SET system_users='system_user1'; => GRANT AUTHENTICATION v_ident to Public; => ENABLE AUTHENTICATION v_ident; Installing and Setting Up an Ident Server To use Ident authentication, you must install one or more packages, depending on your operating system, and enable the Ident server on your Vertica server. oidentd is an Ident daemon that is compatible with Vertica and compliant with RFC Note: You can find the source code and installation instructions for oidentd at the oidentd website. To install and configure Ident authentication for use with your Vertica database, follow the appropriate steps for your operating system: Red Hat 6.x/CentOS 6.x Install oidentd on Red Hat 6.x or CentOS 6.x by running this command: $ yum install oidentd Depending on your configuration, you might receive the following error message: No package oidentd available. In this case, you must install the Red Hat/CentOS Extras Repository. Download and install the Extras Repository from the following location: Red Hat 7.x/CentOS 7.x Install an Ident server on Red Hat 7.x or CentOS 7.x by installing the authd and xinetd packages: $ yum install authd $ yum install xinetd Ubuntu/Debian Install oidentd on Ubuntu or Debian by running this command: $ sudo apt-get install oidentd HPE Vertica Analytic Database (7.2.x) Page 30 of 101

31 SUSE Linux Enterprise Server Install the pidentd and xinted RPMs from the following locations: 11&service_pack=&architecture=i386&package_name=pidentd 11&service_pack=&architecture=i386&package_name=xinetd Post-Installation Steps for Red Hat 6.x/CentOS 6.x and Ubuntu/Debian After you install oidentd on your Red Hat 6.x/CentOS 6.x or Ubuntu/Debian system, continue with the following steps: 1. Verify that the Ident server accepts IPv6 connections to prevent authentication failure. To do so, you must enable this capability. In the script /etc/init.d/oidentd, change the line from: to exec="/usr/sbin/oidentd" exec="/usr/sbin/oidentd -a ::" Then, at the Linux prompt, start oidentd with -a ::. 2. Restart the server with the following command: $ /etc/init.d/oidentd restart Post-Installation Steps for Red Hat 7.x/CentOS 7.x and SUSE Linux Enterprise Server After you install the required packages on your Red Hat 7.x/CentOS 7.x or SUSE Linux Enterprise Server system, continue with the following steps: 1. Enable the auth service in the configuration file located at the following location: /etc/xinet.d/auth. Enter no for the disable option, as this sample configuration file shows. HPE Vertica Analytic Database (7.2.x) Page 31 of 101

32 service auth { disable = no socket_type = stream wait = no user = ident cps = instances = UNLIMITED server = /usr/sbin/in.authd server_args = -t60 --xerror --os } 2. Restart the xinetd service with the following command: $ service xinetd restart Configuring Ident Authentication for Database Users To configure Ident authentication, take the following steps: 1. Create an authentication method that uses Ident. The Ident server must be installed on the same computer as your database, so specify the keyword LOCAL. Vertica requires that the Ident server and database always be on the same computer as the database. => CREATE AUTHENTICATION v_ident METHOD 'ident' LOCAL; 2. Set the Ident authentication parameters, specifying the system users who should be allowed to connect to your database. => ALTER AUTHENTICATION v_ident SET system_users='user1:user2:user3'; 3. Associate the authentication method with the Vertica user. Use a GRANT statement that allows the system user user1 to log in using Ident authentication: => GRANT AUTHENTICATION v_ident TO user1; Kerberos Authentication Kerberos authentication uses the following HPE Vertica Analytic Database (7.2.x) Page 32 of 101

33 Client Package The Kerberos 5 client package communicates with the KDC server. This package is not included as part of the HPE 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 and a realm to which a set of credentials gets assigned. 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: v_vmart_node0001.example.com v_vmart_node0001 then use v_vmart_node0001.example.com as the hostname value. Note: Depending on your configuration it may be safer to use the fully qualified domain name rather than the hostname. 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: Configure Vertica for Kerberos Authentication Configure Clients for Kerberos Authentication HPE Vertica Analytic Database (7.2.x) Page 33 of 101

34 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. 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. HPE Vertica Analytic Database (7.2.x) Page 34 of 101

35 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: o The KDC is on the machine that you are logging in to. o 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. HPE Vertica Analytic Database (7.2.x) Page 35 of 101

36 You must have a user principal for each Vertica Analytic Database user that uses Kerberos Authentication. For example: $ sudo 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 Principal vertica/v_vmart_node0001.example.com@example.com 4 vertica/v_vmart_node0001.example.com@example.com 5. On Vertica run the following to ensure the Kerberos parameters are set correctly: => select parameter_name, current_value from vs_configuration_parameters where parameter_name like 'Ker%' or parameter_name like 'ClientAuthentication'; parameter_name current_value ClientAuthentication host kuser /0 gss, host nokrb /0 md5, local all trust KerberosHostname glcentos5-04.glvpn.com KerberosKeytabFile /scratch_b/qa/krbtest/v_krbtest_node0001_catalog/krb5.keytab KerberosRealm GLVPN.COM KerberosServiceName vertica (5 rows) Creating the Principals and Keytab on Active Directory Active Directory stores information about members of the Windows domain, including users and hosts. HPE Vertica Analytic Database (7.2.x) Page 36 of 101

37 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 : The creation of a Vertica service principal and Vertica host 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. Note: If you use a Vertica cluster behind a load balancer, and plan to connect through the load balancer, the host name is the FQDN of the load balancer (vcluster.dc.com). In this case, you can choose to create one host identity for the entire cluster corresponding to the load balancer FQDN. If you are connecting directly to a Vertica node, you need to repeat this procedure for each node. When you create these accounts, select the following: User Cannot change password Password never expires Note: You can deselect Password never expires, but if you change these user passwords you must recreate the keytab files and reinstall them into Vertica. This includes repeating the entire procedure. 2. 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 HPE Vertica Analytic Database (7.2.x) Page 37 of 101

38 3. 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_SRV_INST For more information about keytab files, see Technet.Microsoft.com. 4. Run the following commands to ensure 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 5. Copy the keytabs you created above, vertica.verticanode01.dc.com.keytab and host.verticanode01.dc.com.keytab, to the Linux host verticanode01.dc.com. 6. 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 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 both the server and host principals for authentication. 7. Copy the new keytab file to the catalog directory. For example: $ cp verticanode01.dc.com.keytab /home/dbadmin/vmart/v_vmart_nodennnn_catalog 8. 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 HPE Vertica Analytic Database (7.2.x) Page 38 of 101

39 Valid starting Expires Service principal 04/08/ :35:25 04/08/ :35:25 renew until 04/15/ :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. 9. Set the right permissions and ownership on the keytab files: $ chmod 600 verticanode01.dc.com.keytab $ chown dbadmin:verticadba verticanode01.dc.com.keytab 10. Set the following Kerberos Authentication Parameters in vertica.conf to inform Vertica about the Kerberos principal: KerberosKeytabFile=<CATALOGDIR>/verticanode01.dc.com.keytab KerberosRealm=DC.COM KerberosServiceName=vertica KerberosHostname=verticanode01.dc.com 11. Restart the Vertica server. 12. 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'; CREATE AUTHENTICATION => ALTER AUTHENTCATION v_kerberos enable; ALTER AUTHENTCATION => GRANT AUTHENTICATION v_kerberos to windowsuser1; GRANT AUTHENTICATION From OS 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 HPE Vertica Analytic Database (7.2.x) Page 39 of 101

40 (1 row) 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. 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 HPE Vertica Analytic Database (7.2.x) Page 40 of 101

41 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 Connecting to Vertica: ODBC DSN Parameters JDBC Connection Properties ADO.NET Connection Properties (vsql) Command Line Options Note: A few scenarios exist in which thevertica server principal name might not match the host name in the connection string. See Troubleshooting Kerberos Authentication for more information. In This Section Configure ODBC and vsql Clients on Linux, HP-UX, AIX, MAC OSX, and Solaris Configure ODBC and vsql Clients on Windows and ADO.NET Configure JDBC Clients on all Platforms Configure ODBC and vsql Clients on Non- Windows Platforms To configure an ODBC or vsql client on Linux, HP-UX, AIX, MAC OSX, or Solaris, 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. 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: HPE Vertica Analytic Database (7.2.x) Page 41 of 101

42 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; HPE Vertica Analytic Database (7.2.x) Page 42 of 101

43 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 in Connecting to Vertica. 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 Parametersin Connecting to Vertica (vsql) Command Line Options in Connecting to Vertica HPE Vertica Analytic Database (7.2.x) Page 43 of 101

44 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 Vertica Linux KDC with Windows Built-in Kerberos Client and Vertica 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 HPE Vertica Analytic Database (7.2.x) Page 44 of 101

45 Directory implementation. However, in this case, Windows is internally communicating with a Linux KDC. See the Microsoft Windows Server Ksetup page for more information. Configure Windows Clients for Kerberos Authentication Depending on which implementation you want to configure, refer to one of the following pages on the Microsoft Server website: To set up Windows clients with Active Directory, refer to Step-by-Step Guide to Kerberos 5 (krb5 1.0) Interoperability. To set up Windows clients with the ksetup utility, refer to the Ksetup page. Authenticate and Connect Clients The KDC can authenticate both an ADO.NET and a vsql client. Note: Use the fully-qualified domain name as the server in your connection string; for example, use host.example.com instead of just host. That way, if the server moves location, you do not have to change your connection string. Verify an ADO.NET Authentication Request and Connection This example shows how to use the IntegratedSecurity=true, setting to specify that the ADO.NET driver authenticate the calling user's Windows credentials: VerticaConnection conn = new VerticaConnection("Database=VMart;Server=host.example.com; Port=5433;IntegratedSecurity=true; KerberosServiceName=vertica;KerberosHostname=vcluster.example.com"); conn.open(); Verify a vsql Authentication Request and Connection 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 HPE Vertica Analytic Database (7.2.x) Page 45 of 101

46 See Also Kerberos Client/Server Requirements vsql Command Line Options in Connecting to Vertica ADO.NET Connection Properties in Connecting to Vertica 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-connectionstring. Implement the LoginModule HPE 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, HP-UX, AIX, MAC OSX, and Solaris 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. HPE Vertica Analytic Database (7.2.x) Page 46 of 101

47 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 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. HPE Vertica Analytic Database (7.2.x) Page 47 of 101

48 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 in Connecting to Vertica Java TM Authentication and Authorization Service (JAAS) Reference Guide (external website) HPE Vertica Analytic Database (7.2.x) Page 48 of 101

49 Troubleshooting Kerberos Authentication These tips can help you avoid issues related to Kerberos authentication with Vertica Analytic Database 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 hosts on the network are all properly configured for your environment. Refer to the Kerberos documentation for your platform for details. System Clocks Out of Sync All Systems Except Red Hat 7/CentOS 7 System clocks in your network must remain in sync for Kerberos authentication to work properly. To do so: 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 Analytic Database 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 HPE Vertica Analytic Database (7.2.x) Page 49 of 101

50 4. Alternatively, run the following command to force clock sync immediately: $ sudo /etc/init.d/ntpd restart For more information, see Set Up Time Synchronization in Installing Vertica 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 Analytic Database 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 Set Up Time Synchronization in Installing Vertica and 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 HPE Vertica Analytic Database (7.2.x) Page 50 of 101

51 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'; 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: HPE Vertica Analytic Database (7.2.x) Page 51 of 101

52 => ALTER DATABASE mydb 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. HPE 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 Analytic Database server. On ODBC, JDBC, and ADO.NET clients, set the host name portion of the server's principal using the KerberosHostName connection string. Tip: On vsql clients, you set the host name portion of the server's principal name using the -K KRB HOST command-line option. The default value is specified by the -h switch, which is the host name of the machine on which the Vertica server is running. -K is equivalent to the drivers' KerberosHostName connection string value. For details, see Command Line Options in Connecting to Vertica. Principal/Host Mismatch Issues and Resolutions The KerberosHostName configuration parameter has been overridden. For example, consider the following connection string: jdbc:vertica://node01.example.com/vmart?user=kuser Because the this connection string includes no explicit KerberosHostName parameter, the driver defaults to the host in the URL (node01.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: HPE Vertica Analytic Database (7.2.x) Page 52 of 101

53 jdbc:vertica://node01.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. You have a DNS name that 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 Analytic Database 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 server2.example.com server3.example.com server4.example.com server5.example.com server6.example.com Now, assume you have the following DNS entries: finance-servers.example.com , , hr-servers.example.com , , 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 You do not have DNS set up on the client machine, so you must connect by IP only. To resolve this issue, specify: HPE Vertica Analytic Database (7.2.x) Page 53 of 101

54 Kerberos -h host name option for the IP address -K host option for server.example.com For example: $ vsql -h 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 About the Kerberos Principal You set the server-side KerberosHostName configuration parameter 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. Rename the KerberosHostName Rename the KerberosHostName to match the name of the Vertica node's host name. For more information, see the following topics in Connecting to Vertica: ODBC DSN Parameters JDBC Connection Properties ADO.NET Connection Properties HPE Vertica Analytic Database (7.2.x) Page 54 of 101

55 LDAP Authentication Lightweight Directory Access Protocol (LDAP) is an authentication method that works like password authentication. The main difference is that the LDAP method authenticates clients trying to access your Vertica database against an LDAP or Active Directory server. Use LDAP authentication when your database needs to authenticate a user with an LDAP or Active Directory server. Before you configure LDAP authentication for your Vertica database, review the following information: LDAP Prerequisites and Definitions LDAP Bind Methods Using LDAP Over SSL/TLS Workflow for Configuring LDAP Bind Workflow for Configuring LDAP Search and Bind Configuring Multiple LDAP Servers LDAP Prerequisites and Definitions Prerequisites Before you configure LDAP authentication for your Vertica database you must have: IP address and host name for the LDAP server. Vertica supports IPv4 and IPv6 addresses. Your organization's Active Directory information. A service account for search and bind. Administrative access to your Vertica database. open-ldap-tools package installed on at least one node. This package includes ldapsearch. Definitions The following definitions are important to remember for LDAP authentication: HPE Vertica Analytic Database (7.2.x) Page 55 of 101

56 Parameter name Host Common name (CN) Domain component (DC) Description IP address or host name of the LDAP server. Vertica supports IPv4 and IPv6 addresses. For more information, see IPv4 and IPv6 for Client Authentication. Depending on your LDAP environment, this value can be either the username or the first and last name of the user. Comma-separated list that contains your organization's domain component broken up into separate values, for example: dc=vertica, dc=com Distinguished name (DN) Organizational unit (OU) samaccountname UID Bind Search and bind Service account Anonymous binding ldapsearch basedn binddn domain.com. A DN consists of two DC components, as in "DC=example, DC= com". Unit in the organization with which the user is associated, for example, Vertica Users. An Active Directory user account field. This value is usually the attribute to be searched when you use bind and search against the Microsoft Active Directory server. A commonly used LDAP account attribute used to store a username. LDAP authentication method that allows basic binding using the DN. LDAP authentication method that must log in to the LDAP server to search on the specified attribute. An LDAP user account that can be used to log in to the LDAP server during bind and search. This account's password is usually shared. Allows a client to connect and search the directory (search and bind) without needing to log in. A command-line utility to search the LDAP directory. It returns information that you use to configure LDAP search and bind. Distinguished name where the directory search should begin. Domain name to find in the directory search. HPE Vertica Analytic Database (7.2.x) Page 56 of 101

57 Parameter name search_attribute Description Text to search for to locate the user record. The default is UID. LDAP Parameters There are several parameters that you need to configure for LDAP authentication. General LDAP Parameters Use the following parameters to configure for either LDAP bind or LDAP bind and search: Parameter name host Description LDAP server URI in the following format: schema://host:optional_port schema is either ldap (for LDAP/Active Directory) or ldaps (for secure LDAP/Active Directory). starttls Optional parameter that defines StartTLS behavior: soft If the server does not support TLS, continue authenticating the user in plain text. This value is equivalent to the -Z option in ldapsearch. hard If server does not support TLS, authentication should fail. This value is equivalent to the -ZZ in ldapsearch. Using ldaps is equivalent to starttls='hard'. However, if you use them together in the same connection string, authentication fails. HPE Vertica Analytic Database (7.2.x) Page 57 of 101

58 Parameter name basedn ldap_continue Description Base DN for search. When set to yes, this parameter allows a connection retry when a user not found error occurs during the previous connection attempt. LDAP Bind Parameters For any other failure error, the system automatically retries the connection. Use the following parameters when authenticating with LDAP bind to create the bind name string. For more information see Workflow for Configuring LDAP Bind. Parameter name binddn_ prefix binddn_ suffix Description First half of the bind string. Second half of bind string. You must use the binddn_prefix and binddn_suffix together. In the following example, the bind name becomes cn=<user_login_ name>;ou=vertica users;dc=verticacorp;dc=com. => ALTER AUTHENTICATION auth_method_name SET binddn_prefix='cn=',binddn_ sufffix='; ou=vertica users;dc=example;dc=com'; domain_ prefix The domain where to find the user name. In the following example, the bind name is verticacorp/<user_ login_name> ALTER AUTHENTICATION auth_method_name SET domain_prefix='example'; _ suffix The part of an address that comes after sign. In the following example, the bind name becomes <user_login_ name>@example.com. HPE Vertica Analytic Database (7.2.x) Page 58 of 101

59 => ALTER AUTHENTICATION auth_method_name SET _sufffix='example.com'; To create the bind name string, you must provide one of the following: Both binddn_prefix and binddn_suffix domain_name _suffix Otherwise, Vertica performs a bind and search operation instead of a bind operation. LDAP Search and Bind Parameters Use the following parameters when authenticating with LDAP search and bind. For more information see Workflow for Configuring LDAP Search and Bind. Parameter name binddn bind_password search_attribute Description Bind DN. Domain name to find in the directory search. Bind password. Required if you specify a binddn. Optional attribute to search for on the LDAP server. The following example shows how to set these three attributes. In this example, it sets binddn to cn=manager,dc=example,dc=com bind_password to secret search_attribute to cn => ALTER AUTHENTICATION auth_method_name SET host=:'ldap://example13', basedn='dc=example,dc=com',binddn='cn=manager,dc=example,dc=com', bind_password='secret',search_attribute='cn'; The binddn and bind_password parameters are optional. If you omit them, Vertica performs an anonymous search. Using LDAP Over SSL/TLS Vertica supports Transport Layer Security (TLS) for client authentication. TLS uses OpenSSL 0.9.8za and SSL v3/transport Layer Security (TLS) 1.0 protocol. HPE Vertica Analytic Database (7.2.x) Page 59 of 101

60 The terms SSL and TLS are often used interchangeably. TLS is the successor to SSL and offers greater security. The original SSL standard was renamed TLS at the time it became open source. The introduction of TLS began with version 1, which is essentially equal to SSL 3. You use openssl commands to create certificates and keys and TLS syntax to create an authentication method. For more information see the Information Security website. You use ALTER AUTHENTICATION to specify LDAP and SSL/TLS parameters. If you specify a host URL that starts with ldaps, the Vertica server authenticates using SSL/TLS on the specified port or on the secure LDAPS port (636). ldaps://abc.dc.com If the LDAP server does not support SSL on that port, authentication fails. If you specify a host URL that starts with ldap and set the LDAP starttls parameter, the Vertica server sends a StartTLS request. This request determines if the LDAP server supports TLS on the specified port or on the default LDAP port (389). => ALTER AUTHENTICATION Ldap1 SET host='ldaps://abc.dc.com', binddn_prefix='cn=', binddn_suffix=',ou=unit2,dc=dc,dc=com', basedn='dc=dc,dc=com', tls_cacert='/home/dc.com.ca.cer', starttls='hard', tls_reqcert='never'; If the LDAP server does not support TLS on that port, the result depends on the value of the starttls parameter: starttls = hard: The Vertica server terminates the authentication process. starttls = soft: The Vertica server proceeds with the authentication but does not use TLS. To configure LDAP over SSL/TLS, use the following configuration parameters: Paramet er Name TLS_ REQCERT TLS_ CADIR Description hard If the client does not provide a certificate, or provides an invalid certificate, it cannot connect. This is the default behavior. never The client does not request or verify a certificate. allow If the client does not provide a certificate or provides an invalid certificate, it can connect anyway. try If the client does not provide a certificate, they can connect. If the client provides an invalid certificate, they cannot connect. Path to the folder with the CA certificates. For example: HPE Vertica Analytic Database (7.2.x) Page 60 of 101

61 Paramet er Name Description ALTER AUTHENTICATION Ldap1 SET TLS_CADIR ='/scratch_b/qa/vertica/qa/vt_scenario/v_ SEC/'; TLS_ CACERT Path to the CA certificate. For example: ALTER AUTHENTICATION Ldap1 SET TLS_CACERT ='/scratch_b/qa/vertica/qa/vt_scenario/v_ SEC/dc.com.ca.cer'; If you do not provide one or more of these parameters, the LDAP server checks to see if the LDAPNOINIT environment variable points to the ldap.conf file. If it does, the server uses the parameters specified in the ldap.conf file. If the LDAP server cannot find the ldap.conf file, authentication fails. The following example shows how to specify the TLS parameters and the LDAP parameters when configuring LDAP over SSL/TLS: => CREATE AUTHENTICATION LDAP1 METHOD 'ldap' HOST :clientip = ' '; => GRANT AUTHENTICATION ldap1 TO user1; => ALTER AUTHENTICATION Ldap1 SET host='ldaps://abc.dc.com', binddn_prefix='cn=', binddn_suffix=',ou=unit2,dc=dc,dc=com', basedn='dc=dc,dc=com', tls_cacert='/home/dc.com.ca.cer', starttls='hard', tls_reqcert='never'; Configuring Multiple LDAP Servers If you need to configure multiple LDAP servers that have different URLs, create a separate authentication record for each server. Use the PRIORITY keyword to indicate which search the LDAP server performs first. The following statements create two authentication methods, vldap1 and vldap2. They specify that the LDAP server first search the entire directory (basedn=dc=example,dc=com) for a DN with an OU attribute Sales. If the first search returns no results, or otherwise fails, the LDAP server next searches for a DN with the OU attribute Marketing: => CREATE AUTHENTICATION vldap1 method "ldap" HOST /8; => ALTER AUTHENTICATION vldap1 SET host='ldap://ldap.example.com/search', basedn='dc=example,dc=com', search_attribute='sales' PRIORITY 1; => GRANT AUTHENTICATION vldap1 to public; => CREATE AUTHENTICATION vldap2 method "ldap" HOST /8; => ALTER AUTHENTICATION vldap2 SET host='ldap://ldap.example.com/search', basedn='dc=example,dc=com', HPE Vertica Analytic Database (7.2.x) Page 61 of 101

62 search_attribute='marketing' PRIORITY 0; => GRANT AUTHENTICATION vldap1 to public; LDAP Bind Methods There are two LDAP methods that you use to authenticate your Vertica database against an LDAP server. Bind Use LDAP bind when Vertica connects to the LDAP server and binds using the CN and password. (These values are the username and password of the user logging into the database). Use the bind method when your LDAP account's CN field matches that of the username defined in your database. For more information see Workflow for Configuring LDAP Bind. Search and Bind Use LDAP search and bind when your LDAP account's CN field is a user's full name or does not match the username defined in your database. For search and bind, the username is usually in another field such as UID or samaccountname in a standard Active Directory environment. Search and bind requires your organization's Active Directory information. This information allows Vertica to log into the LDAP server and search for the specified field. For more information see Workflow for Configuring LDAP Search and Bind. If you are using search and bind, having a service account simplifies your server side configuration. In addition, you do not need to store your Active Directory password. LDAP Anonymous Binding Anonymous binding is an LDAP server function. Anonymous binding allows a client to connect and search the directory (bind and search) without logging in because binddn and bindpasswd are not needed. You also do not need to log in when you configure LDAP authentication using Management Console. Workflow for Configuring LDAP Bind To configure your Vertica database to authenticate clients using LDAP bind, follow these steps: 1. Obtain a service account, as described in LDAP Configuration Considerations. You cannot use the service account in the connection parameters for LDAP bind. HPE Vertica Analytic Database (7.2.x) Page 62 of 101

63 2. Compare the user's LDAP account name to their Vertica username. For example, if John Smith's Active Directory (AD) samaccountname = jsmith, his Vertica username must also be jsmith. However, the LDAP account does not have to match the database user name, as shown in the following example: => CREATE USER r1 IDENTIFIED BY 'password'; => CREATE AUTHENTICATION ldap1 METHOD 'ldap' HOST ' '; => ALTER AUTHENTICATION ldap1 SET HOST= 'ldap:// ',basedn='dc=dc,dc=com',binddn_suffix=',ou=unit2,dc=dc,dc=com',binddn_ prefix='cn=use'; => GRANT AUTHENTICATION ldap1 TO r1; \! ${TARGET}/bin/vsql -p $PGPORT -U r1 -w $LDAP_USER_PASSWD -h ${HOSTNAME} -c "select user_name, client_authentication_name from sessions;" user_name client_authentication_name r1 ldap (1 row) 3. Run ldapsearch from a Vertica node against your LDAP or AD server. Verify the connection to the server and identify the values of relevant fields. Running ldapsearch helps you build the client authentication string needed to configure LDAP authentication. In the following example, ldapsearch returns the CN, DN, and samaccountname fields (if they exist) for any user whose CN contains the username jsmith. This search succeeds only for LDAP servers that allow anonymous binding: $ ldapsearch -x -h b "ou=vertica Users,dc=CompanyCorp,dc=com" '(cn=jsmith*)' cn dn uid samaccountname ldapsearch returns the following results. The relevant information for LDAP bind is in bold: # extended LDIF # # LDAPv3 # base <ou=vertica Users,dc=CompanyCorp,dc=com> with scope subtree # filter: (cn=jsmith*) # requesting: cn dn uid samaccountname # # jsmith, Users, CompanyCorp.com dn:cn=jsmith,ou=vertica Users,dc=CompanyCorp,dc=com cn: jsmith uid: jsmith # search result search: 2 HPE Vertica Analytic Database (7.2.x) Page 63 of 101

64 result: 0 Success # numresponses: 2 # numentries: 1 4. Create a new authentication record based on the information from ldapsearch. In the ldapsearch entry, the CN is username jsmith, so you do not need to set it. Vertica automatically sets the CN to the username of the user who is trying to connect. Vertica uses that CN to bind against the LDAP server. => CREATE AUTHENTICATION v_ldap_bind METHOD 'ldap' HOST ' /0'; => GRANT AUTHENTICATION v_ldap_bind TO public; => ALTER AUTHENTICATION v_ldap_bind SET host='ldap:// /', basedn='dc=companycorp,dc=com', binddn_prefix='cn=', binddn_suffix=',ou=vertica Users,DC=CompanyCorp,DC=com'; For more information see LDAP Parameters Workflow for Configuring LDAP Search and Bind To configure your Vertica database to authenticate clients using LDAP search and bind, follow these steps: 1. Obtain a service account, as described in LDAP Configuration Considerations. 2. From a Vertica node, run ldapsearch against your LDAP or AD server. Verify the connection to the server, and identify the values of relevant fields. Running ldapsearch helps you build the client authentication string needed to configure LDAP authentication. In the following example, ldapsearch returns the CN, DN, and samaccountname fields (if they exist) for any user whose CN contains the username, John. This search succeeds only for LDAP servers that allow anonymous binding: $ ldapsearch -x -h b 'OU=Vertica Users,DC=CompanyCorp,DC=com' -s sub -D 'CompanyCorp\jsmith' -W '(cn=john*)' cn dn uid samaccountname 3. Review the results that ldapsearch returns.the relevant information for search and bind is in bold: HPE Vertica Analytic Database (7.2.x) Page 64 of 101

65 # extended LDIF # # LDAPv3 # base <OU=Vertica Users,DC=CompanyCorp,DC=com> with scope subtree # filter: (cn=john*) # requesting: cn dn samaccountname # # John Smith, Vertica Users, CompanyCorp.com dn: CN=jsmith,OU=Vertica Users,DC=CompanyCorp,DC=com cn: Jsmith samaccountname: jsmith # search result search: 2 result: 0 Success # numresponses: 2 # numentries: 1 4. Create the client authentication record. The cn attribute contains the username you want jsmith. Set your search attribute to the CN field so that the search finds the appropriate account. => CREATE AUTHENTICATION v_ldap_bind_search METHOD 'ldap' HOST ' '; => GRANT AUTHENTICATION v_ldap_bind_search TO public; => ALTER AUTHENTICATION v_ldap_bind_search SET host='ldap:// ', basedn='ou=vertica,dc=companycorp,dc=com', binddn='cn=jsmith,ou=vertica Users,DC=CompanyCorp,DC=com', bind_password='password', search_attribute='cn'; For more information see LDAP Search and Bind Parameters LDAP Link Service LDAP Link enables synchronization between the LDAP and Vertica servers. This eliminates the need for you to manage two sets of users and groups, one on the LDAP server and another on the Vertica server. With LDAP synchronization, the Vertica server becomes a replication database for the LDAP server. Automatic Synchronization With LDAP Link the Vertica server closely integrates with an existing directory service such as MS Active Directory or OpenLDAP. The Vertica server automatically synchronizes: LDAP users to Vertica users LDAP groups to Vertica groups HPE Vertica Analytic Database (7.2.x) Page 65 of 101

66 You manage all user and group properties in the LDAP server. If you are the Vertica database administrator, you need only to set up permissions for Vertica Analytic Database access on the users and groups. Configure LDAP Link with LDAP Link connection parameters that reside in the catalog. See Set LDAP Link Parameters for more information. Enable LDAP Link Enable LDAP Link as as shown in this example: => ALTER DATABASE <dbname> SET PARAMETER LDAPLinkURL='ldap://glw2k8-64.dc.com', LDAPLinkSearchBase='dc=DC,dc=com', LDAPLinkBindDN='CN=jsmith,OU=QA,DC=dc,DC=com, LDAPLinkBindPswd='password', LDAPLinkFilterGroup='(objectClass=group)', SET LDAPLinkOn=1; => SELECT ldap_link_sync_start(); See LDAP Link Parameters. LDAP Link Workflow After you enable LDAP Link, synchronization occurs according to this workflow: HPE Vertica Analytic Database (7.2.x) Page 66 of 101

67 1. The System Administrator creates users and user groups on the LDAP server. 2. The System Administrator sets up LDAP Link service parameters as required and enables the service. 3. Using the LDAP Link service, Vertica Analytic Database replicates the users and user groups from the Application LDAP to the Vertica database. 4. The LDAP server uses Kerberos (KDC) to authenticate the user logging in to Vertica. The LDAP user can log into Vertica if assigned the appropriate authentication type. After login, you can grant users privileges using GRANT statements or as part of a Group. HPE Vertica Analytic Database (7.2.x) Page 67 of 101

68 Note: After synchronization the Vertica Analytic Database user does not have an associated authentication method. To allow the user to login, you must assign an authentication method to the user. See Implementing Client Authentication. Using LDAP Link When you implement LDAP Link the following are directly affected and help you manage and monitor the LDAP Link - Vertica Analytic Database synchronization: User and Group management LDAP Link User Flag Blocked Commands Client Authentication types User and Group Management Users and groups created on the LDAP server have a specific relationship with those users and groups replicated to the Vertica server: The user-group relationship on the LDAP server is maintained when those users and groups (roles) are synchronized with Vertica Analytic Database. If a user or group name exists on the Vertica database and a user or group with the same names is synchronized from the LDAP Server using LDAP Link, the users or groups become conflicted. Vertica can not support multiple users with the same name. For a resolution of this conflict, see User Conflicts. LDAP Link uses the entries in the dn: section of the LDAP configuration file as the unique user identifier when synchronizing a user to the Vertica Analytic Database: dn: cn=user1,ou=dev,dc=example,dc=com cn: user1 ou: dev id: user1 The uid parameter in the LDAP configuration file indicates the LDAP user name. uid: user1 Upon synchronization, the dn: entry gets mapped to the uid: to identify the Vertica Analytic Database user. If you change a setting in the dn: and do not change the uid: LDAP Link interprets the user as a new user when re-synchronizing with the Vertica Analytic Database. In this HPE Vertica Analytic Database (7.2.x) Page 68 of 101

69 case, the existing Vertica Analytic Database user with that uid: gets deleted from Vertica and a new Vertica Analytic Database user is created. If you change the uid: and not the dn: on LDAP, the uid on the Vertica Analytic Database gets updated to the new uid. Since you did not change the dn: LDAP Link does not interpret the user as a new user. LDAP Link User Flag As a dbadmin user, you can access the vs_users table to monitor user behavior on the Vertica Analytic Database. The vs_users table contains an ldapdn field that identifies whether or not the Vertica Analytic Database user is also an LDAP Link user. This example shows the ldapdn field set to dn indicating the Vertica Analytic Database user is also an LDAP Link user: => SELECT * FROM vs_users; -[ RECORD 1 ] oid name dbadmin schema 0 usercreatedb t usersuper t usercatupd f passwd passwdcreatetime :39: isnullpasswd t passwdhistory 1 failedlogins 0 locked 0 locktime :00:00-05 acctexpired f profile resourcepool 0 memorycap -1 tempspacecap -1 runtimecap num_all_roles 3 all_roles dbduser*, dbadmin*, pseudosuperuser* num_default_roles 3 default_roles dbduser*, dbadmin*, pseudosuperuser* admin_option 3 search_path salt Vertica securityalgorithm 0 clientauthentications 0 ldapdn dn ldapurihash 0 Blocked Commands Be aware that the following SQL statements are blocked for Vertica Analytic Database users with ldapdn set to dn in the vs_users table: HPE Vertica Analytic Database (7.2.x) Page 69 of 101

70 DROP USER and DROP ROLE ALTER ROLE RENAME ALTER USER name IDENTIFIED BY 'password' [REPLACE 'old_password'] ALTER USER name PASSWORD EXPIRE ALTER USER name PROFILE ALTER USER name SECURITY_ALGORITHM... ALTER USER name DEFAULT ROLE role-name GRANT (Role) Client Authentication Types LDAP user and groups cannot log into Vertica if client authentication is not assigned to the user or group. You can use the following valid authentication types for LDAP users and groups: GSS Ident LDAP Reject Trust LDAP Link Parameters Use LDAP Link parameters to determine: LDAP Link operations, such as enabling or disabling LDAP Link and how often to perform replication Authentication parameters, including SSL authentication parameters Users and groups that inherit unowned objects How to resolve conflicts HPE Vertica Analytic Database (7.2.x) Page 70 of 101

71 Set LDAP Link Parameters This example shows how you can set: The URL of the LDAP server (LDAPLinkURL) and The base DN from where to start replication (LDAPLinkSearchBase) You also see how to set the LDAP Link Bind authentication parameters (LDAPLinkBindDN and LDAPLinkBindPswd) and enables LDAP Link (LDAPLinkOn). => ALTER DATABASE mydb1 SET PARAMETER LDAPLinkURL='ldap:// ', LDAPLinkSearchBase='dc=corp,dc=com',LDAPLinkBindDN='dc=corp,dc=com',LDAPLinkBindPswd='password'; => ALTER DATABASE mydb1 SET PARAMETER LDAPLinkOn = '1'; General and Connection Parameters Parameter LDAPLinkOn LDAPLinkURL Description Enables or disables LDAP Link. Valid Values: 0 LDAP Link disabled 1 LDAP Link enabled Default value: 0 The LDAP server URL. Example: SET PARAMETER LDAPLinkURL='ldap://glw2k8-64.dc.com'; LDAPLinkInterval LDAPLinkFirstInterval LDAPLinkRetryInterval The time interval, in seconds, by which the LDAP Server and Vertica server synchronize. Default Value: (one day). The first interval, in seconds, for LDAP/Vertica synchronization after the clerk node joins the cluster. Default Value: 120 The time, in seconds, the system waits to retry a failed synchronization. Default Value: 10 HPE Vertica Analytic Database (7.2.x) Page 71 of 101

72 Parameter LDAPLinkRetryNumber LDAPLinkSearchBase Description The number of retry attempts if synchronization failed. Default Value: 10. The base dn from where to start replication. Example: SET PARAMETER LDAPLinkSearchBase='ou=vertica,dc=mycompany,dc=com'; Vertica recommends using a separate OU for database users. LDAPLinkSearchTimeout LDAPLinkScope The timeout length, in seconds, for the LDAP search operation during an LDAP Link Service run. Default Value: 10 Indicates what dn level to replicate. Valid Values: sub Replicate entire subtree under basedn one Replicate to one level under basedn base Replicate only the basedn level If you decrease the scope (for example, sub to one), some users may not be recognized during the next synchronization. Default Value: sub LDAPLinkFilterUser LDAPLinkFilterGroup LDAPLinkGroupName LDAPLinkGroupMembers Determines how to filter users to be replicated. Default Value: "(objectclass=inetorgperson)" Determines how to filter groups to be replicated. Default Value: "(objectclass=groupofnames)" [Optional] The LDAP field to use when creating a role name in Vertica. Default Value: cn The LDAP group name linked to a user. HPE Vertica Analytic Database (7.2.x) Page 72 of 101

73 Parameter Description Default Value: member LDAPLinkUserName The LDAP field to use when creating a user name in Vertica. Authentication Parameters Parameter LDAPLinkBindDN Description The LDAP Bind DN used for authentication. Example: SET PARAMETER LDAPLinkBindDN='CN=amir,OU=QA,DC=dc,DC=com'; LDAPLinkBindPswd The valid password for the LDAP Bind DN to access the server. Only accessible by the dbadmin user. Example: SET PARAMETER LDAPLinkBindPswd='password'; SSL Authentication Parameters Parameter LDAPLinkStartTLS LDAPLinkTLSReqCert Description [Optional] Specifies whether or not to use the StartTLS operation during bind. You can only use this parameter if the LDAP server's URL is "ldap://..." (not "ldaps://..." Valid Values: 0 - Do not use starttls 1 - Use starttls Default Value: 0 [Optional] Specifies how to manage certificates when using TLS. Valid Values: allow connection is successful even if the client does not provide a certificate or provides an invalid certificate. HPE Vertica Analytic Database (7.2.x) Page 73 of 101

74 Parameter Description hard connection is unsuccessful if the client does not provide a certificate or provides an invalid certificate. try connection is successful if the client does not provide a certificate. A connection is unsuccessful If the client provides an invalid certificate. never The client does not request or verify a certificate. For more information see Using LDAP Over SSL/TLS Default Value: allow LDAPLinkTLSCACert [Optional] The path to the CA certificates. Miscellaneous Parameters Parameter GlobalHeirUserName Description [Optional] The user name which inherits objects previously owned by dropped users (using CASCADE). This prevents the loss of data owned by dropped users. If the user name indicated here does not exist, the system automatically creates the user. Example: SET PARAMETER GlobalHeirUsername='userheir1'; If you do not set this parameter, the SQL command DROP USER CASCADE works as intended. LDAPLinkConflictPolicy LDAPLinkDryRun Determines how to resolve a user conflict. Valid Values: IGNORE Ignores the incoming LDAP user and maintains the existing Vertica user. MERGE Converts the existing user to an LDAP user. Default Value: MERGE [Optional] Tests the connection to the LDAP server and logs the response without doing a synchronization. Also tests if parameters are correctly set. HPE Vertica Analytic Database (7.2.x) Page 74 of 101

75 Parameter Description Valid Values: 0 - Disables LDAPLinkDryRun 1 - Enables LDAPLinkDryRun Default Value: 0 See Setting and Clearing Configuration Parameters for information on setting LDAP Link parameters. Note: When you change any Connection or Authentication parameter, LDAP Link reconnects and re-initializes the synchronization. Troubleshooting LDAP Link Issues Various issues can arise with LDAP Link Service, including: Disconnected (Orphaned) Users and Groups Lost Objects User Conflicts Disconnected (Orphaned) Users and Roles Vertica Analytic Database users and groups synchronized through LDAP Link can become disconneted, or orphaned, if an issue arises with the LDAP Link service. For example, users and groups become orphaned when you change the connection to the LDAP server as the following scenario describes: 1. Create an LDAP connection as follows: => ALTER DATABASE MyDB1 SET PARAMETER LDAPLinkURL='ldap://ebuser', LDAPLinkSearchBase='dc=example,dc=com', LDAPLinkBindDN='mega', LDAPLinkBindPswd='$megapassword$'; => ALTER DATABASE MyDB1 SET PARAMETER LDAPLinkOn = '1'; 2. Run an LDAP Link session to synchronize LDAP and Vertica users. 3. Change one or more connection parameters from Step 1. You can change the connection only if you change one of the LDAPLinkURL or LDAPLinkSearchBase parameters. HPE Vertica Analytic Database (7.2.x) Page 75 of 101

76 4. Run another LDAP Link session. The system attempts to re-synchronize LDAP and Vertica users. Since the connection has changed, the existing Vertica users cannot be synchronized with the LDAP users from the new connection. These Vertica users become orphaned. As a dbadmin user, you can identify orphaned users by comparing the ldapurihash field in vs_users against the current LDAP connection hash in the system-table vs_ ldap_link_info. When the hashes do not match, the user is orphaned. Example: => SELECT name, ldapdn, ldapurihash FROM vs_users; name ldapdn ldapurihash dbadmin cn=u1,dc=example,dc=com 8 (1 rows) The mismatched hash numbers indicate user name user2 is an orphaned user. Orphaned Vertica users cannot connect to the LDAP server and cannot login to Vertica using LDAP authentication (however, other authentication methods assigned to the user work). In this case, you can delete the orphaned Vertica user and run the LDAP Link service to resynchronize users. Lost Objects When you delete users or groups from linked LDAP, the LDAP Link service removes the same users and groups from Vertica Analytic Database. However, the service does not delete objects owned by the deleted user, and these objects become lost. Use the GlobalHeirUserName parameter to assign the objects to a new owner. Example: => ALTER DATABASE example_db SET PARAMETER GlobalUserHeir=user1; This creates a new user named user1, if it does not exist. The GlobalHeirUsername user serves as the new parent for all the objects owned by deleted users. By default, this parameter is not set, which causes objects belonging to deleted users to become lost. User Conflicts Vertica Analytic Database users and groups synchronized using LDAP Link can become conflicted. Such conflicts can occur, for example, when you create a new user or group on the LDAP server and another user or group with the same name exists on the Vertica Analytic Database. As a dbadmin user, use the LDAPLinkConflictPolicy parameter to resolve user conflicts: HPE Vertica Analytic Database (7.2.x) Page 76 of 101

77 LDAPLinkConflictPolicy=IGNORE - Ignores the incoming LDAP users and maintains the existing Vertica user LDAPLinkConflictPolicy=MERGE - Merges the incoming LDAP user with the Vertica user and converts the database user to an LDAP user retaining the database user's objects Example: => ALTER DATABASE example_db SET PARAMETER LDAPLinkConflictPolcy='MERGE'; The default is MERGE. If you change LDAPLinkConflictPolicy, the change takes affect on the next synchronization. Monitoring LDAP Link Use the dc_ldap_link_events table to monitor events that occurred during an LDAP Link synchronization: => SELECT transaction_id, event_type, entry_name, entry_oid FROM dc_ldap_link_events; transaction_id event_type entry_name entry_oid SYNC_STARTED SYNC_FINISHED PROCESSING_STARTED USER_CREATED tuser (4 rows) TLS/SSL Server Authentication The terms SSL and TLS are often used interchangeably. This document uses both terms. TLS is the successor to SSL and offers greater security. The original SSL standard was renamed TLS at the time it became open source. The introduction of TLS began with version 1, which is essentially equal to SSL 3. You use openssl commands to create certificates and keys and TLS syntax to create an authentication method. To protect privacy and verify data integrity, you can configure Vertica and database clients to use Secure Socket Layer (SSL). SSL allows secure connection and communication between the client and the server. The SSL protocol uses a trusted third party called a Certificate Authority (CA). Both the owner of a certificate and the party that relies on the certificate trust the CA. Vertica supports the following authentication methods under Transport Layer Security (TLS) v1.0, v1.1, and v1.2 protocol: HPE Vertica Analytic Database (7.2.x) Page 77 of 101

78 SSL server authentication Lets the client confirm the server's identity. The client verifies that the server's certificate and public key are valid and were issued by a certificate authority (CA) listed in the client's list of trusted CAs. This authentication helps prevent man-in-the-middle attacks. See "Prerequisites for SSL Server Authentication and SSL Encryption" in SSL Overview and Configuring SSL. SSL client authentication (Optional) Lets the server confirm the client's identity. The server verifies that the client's certificate and public key are valid and were issued by a certificate authority (CA) listed in the server's list of trusted CAs. Client authentication is optional because Vertica can authenticate the client at the application protocol level through user name and password credentials. See "Optional Prerequisites for SSL Server and Client Mutual Authentication" in SSL Overview. Encryption Encrypts data sent between the client and database server. This method significantly reduces the likelihood that the data can be read if the connection between the client and server is compromised. Encryption works at both ends of a transaction, regardless of whether SSL Client Authentication is enabled. See "Prerequisites for SSL Server Authentication and SSL encryption" in SSL Overview and Configuring SSL. Data integrity Verifies that data sent between the client and server has not been altered during transmission. Note: For server authentication, Vertica supports using RSA encryption with ephemeral Diffie-Hellman (DH). DH is the key agreement protocol. Certificate Authority The CA issues electronic certificates to identify one or both ends of a transaction. These certificates to verify ownership of a public key by the name on the certificate. Public and Private Keys A CA issues digital certificates that contain a public key and the identity of the owner. The public key is available to all users through a publicly accessible directory. However, private keys are confidential to their respective owners. When you use a private/public key pair, the data is encrypted by one key and decrypted by its corresponding key. If encrypted with a public key, data can be decrypted by its corresponding private key only. HPE Vertica Analytic Database (7.2.x) Page 78 of 101

79 If encrypted with a private key, data can be decrypted by its corresponding public key only. For example, suppose Alice wants to send confidential data to Bob. Because she wants only Bob to read it, she encrypts the data with Bob's public key. Even if someone else gains access to the encrypted data, it remains protected. Because only Bob has access to his corresponding private key, he is the only person who can decrypt Alice's encrypted data back into its original form. SSLAuthentication SSL Authentication To protect privacy and verify data integrity, you can configure Vertica and database clients to use Secure Socket Layer (SSL). SSL allows secure connection and communication between the client and the server. The SSL protocol uses a trusted third party called a Certificate Authority (CA). Both the owner of a certificate and the party that relies on the certificate trust the CA. Vertica supports the following authentication methods under Transport Layer Security (TLS) v1.0, v1.1, and v1.2 protocol: SSL server authentication Lets the client confirm the server's identity. The client verifies that the server's certificate and public key are valid and were issued by a certificate authority (CA) listed in the client's list of trusted CAs. This authentication helps prevent man-in-the-middle attacks. See "Prerequisites for SSL Server Authentication and SSL Encryption" in SSL Overview and Configuring SSL. SSL client authentication (Optional) Lets the server confirm the client's identity. The server verifies that the client's certificate and public key are valid and were issued by a certificate authority (CA) listed in the server's list of trusted CAs. Client authentication is optional because Vertica can authenticate the client at the application protocol level through user name and password credentials. See "Optional Prerequisites for SSL Server and Client Mutual Authentication" in SSL Overview. Encryption Encrypts data sent between the client and database server. This method significantly reduces the likelihood that the data can be read if the connection between the client and server is compromised. Encryption works at both ends of a transaction, regardless of whether SSL Client Authentication is enabled. See "Prerequisites for SSL Server Authentication and SSL encryption" in SSL Overview and Configuring SSL. HPE Vertica Analytic Database (7.2.x) Page 79 of 101

80 Data integrity Verifies that data sent between the client and server has not been altered during transmission. Note: For server authentication, Vertica supports using RSA encryption with ephemeral Diffie-Hellman (DH). DH is the key agreement protocol. Certificate Authority The CA issues electronic certificates to identify one or both ends of a transaction. These certificates to verify ownership of a public key by the name on the certificate. Public and Private Keys A CA issues digital certificates that contain a public key and the identity of the owner. The public key is available to all users through a publicly accessible directory. However, private keys are confidential to their respective owners. When you use a private/public key pair, the data is encrypted by one key and decrypted by its corresponding key. If encrypted with a public key, data can be decrypted by its corresponding private key only. If encrypted with a private key, data can be decrypted by its corresponding public key only. For example, suppose Alice wants to send confidential data to Bob. Because she wants only Bob to read it, she encrypts the data with Bob's public key. Even if someone else gains access to the encrypted data, it remains protected. Because only Bob has access to his corresponding private key, he is the only person who can decrypt Alice's encrypted data back into its original form. SSL Overview Before you implement SSL security, obtain the appropriate certificate signed by a certificate authority (CA) and private key files. Copy the certificate file to the database catalog directory. These files must use the Privacy-Enhanced Mail (PEM) format. PEM is the standard file format for Certificates and can be included in ascii or rich text documents. For reference information on SSL use the following links: OpenSSL Documentation OpenSSL Support HPE Vertica Analytic Database (7.2.x) Page 80 of 101

81 OpenSSL FAQs OpenSSL Release You can also implement SSL with LDAP authentication. For more information see Using LDAP Over SSL/TLS. Set Up SSL Server Authentication and SSL Encryption Follow these steps to set up SSL server authentication: Important: If you do not perform these steps, database operation may be compromised. If the client cannot authenticate the server, the database does not start. 1. Copy the server certificate file (server.crt) and private key (server.key) to one of your server hosts in the cluster. 2. Distribute these files to all server hosts using the instruction in Distributing Certificates and Keys. The public key contained in the certificate and the corresponding private key allow the SSL connection to encrypt the data to protect data integrity 3. Because using SSL mutual mode requires that the client verify the server's certificate key, copy the root.crt file. Use the JDBC or vsql options, as appropriate For JDBC If you are using SSL mutual mode with JDBC, copy the root.crt file to a location on any one of the clients. After you copy the file to the client, root.crt is incorporated into the truststore. For more information, see Generating SSL Certificates and Keys in Generating SSL Certificates and Keys. For vsql: If the VSQL_HOME environment variable is not set, copy the root.crt file to the.vsql subdir of the login user's home directory (for example, ~/.vsql/root.crt). If the VSQL_HOME environment variable is set, copy the root.crt file to the.vsql subdir of the target directory (for example, $vsql_home/.vsql/root.crt). The root.crt file contains either the server's certificate or the Certificate Authority that issued the server certificate. HPE Vertica Analytic Database (7.2.x) Page 81 of 101

82 Set SSL Server for Mutual Mode Authentication Use SSL Mutual Mode to have both server and client mutually authenticate themselves with SSL keys. With SSL Mutual Mode the server requests a certificate from the client and the client requests a certificate from the server. Set up SSL Mutual Mode as follows: 1. Copy the root.crt file to one server host in the cluster. This file is distributed to all server hosts when you distribute certificates and keys. See Distributing Certificates and Keys. The root.crt file has the same name on the client and server though the file contents can differ. The contents are identical only if the client and server certificates were used by the same root certificate authority (CA). 2. Copy the client certificate file (client.crt) and private key (client.key) to each client. For vsql: If the VSQL_HOME environment variable is set, copy the file to the.vsql subdirectory of the target directory set up in the environment variable (e.g., $vsql_home/.vsql/client.crt). If the VSQL_HOME environment variable is not set, copy the two files to the.vsql subdir of the login user's home directory. (e.g., ~/.vsql/client.crt). If you are using either ODBC or JDBC, you can place the files anywhere on your system. Then, provide the location in the connection string (ODBC/JDBC) or ODBCINI (ODBC only). See Configuring SSL for ODBC Clients and Configuring SSL for JDBC Clients. Important: If you're using ODBC, the private key file (client.key) must have read and write permissions only for the dbadmin user. For example: chmod 600 client.key Do not provide any additional permissions or extend them to any other users. Generating SSL Certificates and Keys Generating SSL certificates and keys, you must perform the following tasks: Create a Certificate Authority Private Key and Public Certificatethat can then be used to sign server and client keys. Important: In a production environment, always use certificates signed by a HPE Vertica Analytic Database (7.2.x) Page 82 of 101

83 Certificate Authority. Create the Server Private key and Certificate, and request a new server certificate that includes a public key. Create the Client Private key and Certification, and request a new client certificate that includes a public key. For more detailed information on creating signed certificates, refer to the OpenSSL documentation. The documentation includes hypothetical examples and sample procedures to show how to create certificates and keys. The commands shown allow many other possible options not used in these examples. Create commands based on your specific environment. Create a Certificate Authority Private Key and Public Certificate Create a Certificate Authority (CA) private key and public certificate. For more information on using the following commands. see the OpenSSL documentation. 1. Use the openssl genrsa command to create a CA private key. The value 1024 indicates the certificate file size. $ openssl genrsa -out new_servercakey.pem Use the openssl req command to generate a CA public certificate. $ openssl req -config openssl_req_ca.conf -newkey rsa:1024 -x509 -days key new_ servercakey.pem -out new_serverca.crt Enter the following sample CA certificate values in response to openssl command line prompts. The actual values you enter here will be different than the sample values. Rather than enter these values from command line prompts, you can optionally provide the same information in.conf files. For example, openssl_req_ca.conf in the preceding example. HPE Vertica Analytic Database (7.2.x) Page 83 of 101

84 Country Name (2 letter code) [GB]:US State or Province Name (full name) [Berkshire]:Massachusetts Locality Name (e.g., city) [Newbury]:Cambridge Organization Name (e.g., company) [My Company Ltd]:CorpName Organizational Unit Name (e.g., section) []:TechSupport Common Name (e.g., your name or server hostname) []:myhost Address 3. Include one unique Distinguished Name (DN) for each certificate that you create. In the preceding examples, the DN is the Organizational Unit Name. You now have a CA private key, new_servercakey.pem. You also have a CA public certificate, new_serverca.crt. Use both the private key and the public certificate in the procedures that follow for creating server and client certificates. Generating Certificates and Keys for MC A certificate signing request (CSR) is a block of encrypted text generated on the server on which the certificate is used. You send the CSR to a certificate authority (CA) to apply for a digital identity certificate. The CA uses the CSR to create your SSL certificate from information in your certificate; for example, organization name, common (domain) name, city, and country. Management Console (MC) uses a combination of OAuth (Open Authorization), Secure Socket Layer (SSL), and locally-encrypted passwords to secure HTTPS requests between a user's browser and MC, and between MC and the agents. Authentication occurs through MC and between agents within the cluster. Agents also authenticate and authorize jobs. The MC configuration process sets up SSL automatically, but you must have the openssl package installed on your Linux environment first. When you connect to MC through a client browser, Vertica assigns each HTTPS request a self-signed certificate, which includes a timestamp. To increase security and protect against password replay attacks, the timestamp is valid for several seconds only, after which it expires. To avoid being blocked out of MC, synchronize time on the hosts in your Vertica cluster, and on the MC host if it resides on a dedicated server. To recover from loss or lack of synchronization, resync system time and the Network Time Protocol. See Set Up Time Synchronization in Installing Vertica. Create a Certificate and Submit it for Signing For production, you must use certificates signed by a certificate authority. You can create and submit a certificate and when the certificate returns from the CA, import the certificate into MC. HPE Vertica Analytic Database (7.2.x) Page 84 of 101

85 Use the openssl command to generate a new CSR: $ openssl req -new -key /opt/vconsole/config/keystore.key -out server.csr When you press Enter, you are prompted to enter information to be incorporated into your certificate request. Some fields contain a default value, which you should change for security reasons. Other fields you can leave blank, such as password and optional company name. To leave the field blank, type '.'. Important: The keystore.key value for the -key option creates private key for the keystore. If you generate a new key and import it using the Management Console interface, the MC process does restart properly. You must restore the original keystore.jks file and restart Management Console. This information is contained in the CSR and shows both the default and replacement values: Country Name (2 letter code) [GB]:USState or Province Name (full name) [Berkshire]:Massachusetts Locality Name (eg, city) [Newbury]: Cambridge Organization Name (eg, company) [My Company Ltd]:HP Organizational Unit Name (eg, section) []:Information Management Common Name (eg, your name or your server's hostname) []:console.vertica.com Address []:mcadmin@vertica.com The Common Name field is the fully qualified domain name of your server. Your entry must exactly match what you type in your web browser, or you receive a name mismatch error. Self-Sign a Certificate for Testing To test your new SSL implementation, you can self-sign a CSR using either a temporary certificate or your own internal CA, if one is available. Note: A self-signed certificate generates a browser-based error notifying you that the signing certificate authority is unknown and not trusted. For testing purposes, accept the risks and continue. The following command generates a temporary certificate, which expires after 365 days: $ openssl x509 -req -days 365 -in server.csr -signkey /opt/vconsole/config/keystore.key -out server.crt Enter passphrase for /opt/vconsole/config/keystore.key: Enter same passphrase again: The previous example prompts you for a passphrase. This is required for Apache to start. To implement a passphrase you must put the SSLPassPhraseDialog directive in the appropriate Apache configuration file. For more information see your Apache documentation. This example shows the command's output to the terminal window: HPE Vertica Analytic Database (7.2.x) Page 85 of 101

86 Signature oksubject=/c=us/st=massachusetts/l=billerica/o=hp/ou=it/ Getting Private key You can now import the self-signed key, server.crt, into Management Console. See Also Configuring SSL Key and Certificate Management Tool Importing a New Certificate to MC Use this procedure to import a new certificate into Management Console. Note: To generate a new certificate for Management Console, you must use the keystore.key file, which is located in /opt/vconsole/config on the server on which you installed MC. Any other generated key/certificate pair causes MC to restart incorrectly. You will then have to restore the original keystore.jks file and restart Management Console. See Generating Certifications and Keys for Management Console. 1. Connect to Management Console, and log in as an administrator. 2. On the Home page, click MC Settings. 3. In the button panel on the left, click SSL certificates. 4. To the right of "Upload a new SSL certificate," click Browse to import the new key. 5. Click Apply. 6. Restart Management Console. Configuring SSL Configure SSL for each server in the cluster. 1. Verify that you have performed at least the minimum steps required in SSL Overview for server authentication and encryption and, optionally, for mutual authentication. 2. Next, verify that you have performed the steps in Distributing Certificates and Keys. HPE Vertica Analytic Database (7.2.x) Page 86 of 101

87 Important: Before you set the Security Parameters SSLCertificate and SSLPrivateKey, you must first set the EnableSSL parameter. Admintools sets these parameters for you when you perform the procedure steps listed in Distributing Certificates and Keys. Alternatively, you can use vsql to set the parameters using the ALTER DATABASE statement. For more information on setting configuration parameters see ALTER DATABASE. These parameters are also automatically set during upgrade to 7.1 if you set EnableSSL=1 in the previous version. 3. Set the EnableSSL parameter to 1. By default, EnableSSL is set to 0 (disabled). => ALTER DATABASE mydb SET EnableSSL = 1; 4. Restart the database. 5. If you are using either ODBC or JDBC, configure SSL for the appropriate client: Configuring SSL for ODBC Clients Configuring SSL for JDBC Clients vsql automatically tries to connect using SSL. If a connection fails, and your server is started in SSL Server Mode, vsql attempts to make a second connection over clear text. If you start the server in SSL Mutual Mode, the connection fails without vsql attempting to connect over clear text. Configuring SSL for ODBC Clients Configuring SSL for ODBC clients requires that you set the SSLMode connection property. If you want to configure optional SSL client authentication, you must also configure the Security Parameters SSLKeyFile and SSLCertFile connection properties. Where to Configure DSN The method you use to configure the DSN depends on the type of client operating system you are using: Linux and UNIX Enter the connection properties in the odbc.ini file. See Creating an ODBC DSN for Linux, Solaris, AIX, and HP-UX Clients. Microsoft Windows Enter the connection properties in the Windows Registry. See Creating an ODBC DSN for Windows Clients. HPE Vertica Analytic Database (7.2.x) Page 87 of 101

88 For Windows ODBC you can set connection string properties within the ODBC Data Source Administrator GUI, under the tab, Client Settings. Properties you can set include the SSL cert file and SSL key file fields. Set SSLMode Connection Property Set the SSLMode connection property to one of the following options for the DSN: Property require prefer allow disable Description Requires the server to use SSL. If the server cannot provide an encrypted channel, the connection fails. (Default value) Indicates your preference that the server to use SSL.The first connection to the database tries to use SSL. If that connection fails, a second connection is attempted over a clear channel. Makes a connection to the server whether the server uses SSL or not. The first connection attempt to the database is made over a clear channel. If that connection fails, a second connection is attempted over SSL. Never connects to the server using SSL. This setting is typically used for troubleshooting. Enable SSL Mutual Mode Authentication You can optionally configure SSL mutual mode by setting the following database Security Parameters: SSLKeyFile - set this connection property to the file path and name of the client's private key. This key can reside anywhere on the client. SSLCertFile - set this connection property to the file path and name of the client's public certificate. This file can reside anywhere on the client. HPE Vertica Analytic Database (7.2.x) Page 88 of 101

89 Configuring SSL for JDBC Clients This page explains how to configure SSL Authentication for JDBC clients. This involves the following: Set required properties. Enable SSL. Optionally run the SSL Debug Utility. Set Required Properties Set Properties When Location or the Keystore/Truststore Is Not the Default If you are using a location or the keystore/truststore that is not the default, set the following system properties so that the JRE can find your keystore/truststore: $ javax.net.ssl.keystore $ javax.net.ssl.truststore Set Properties When Keystore/Truststore Is Password Protected If your keystore/truststore is password protected, set the following system properties so that the JRE has access to it: $ javax.net.ssl.keystorepassword $ javax.net.ssl.truststorepassword Enable SSL Enable SSL in the JDBC Driver by setting the SSL property to true in one of the following ways: Set ssl=true in a connection string/url by calling SslEnabled(true) on the DataSource, or Use a Properties object parameter Run the SSL Debug Utility After configuring SSL for JDBC, optionally run the following command to enable the debug utility for SSL: $ -Djavax.net.debug=ssl You can use several debug specifiers (options) with the debug utility. The specifiers help narrow the scope of the debugging information that is returned. For example, you could specify one of the options that prints handshake messages or session activity. HPE Vertica Analytic Database (7.2.x) Page 89 of 101

90 For information on the debug utility and its options, see Debugging Utilities in the Oracle document, JSSE Reference Guide. For information on interpreting debug information, refer to the Oracle document, Debugging SSL/TLS Connections. Distributing Certificates and Keys Before you can distribute certifications and keys to all hosts in a cluster, you must obtain the appropriate certificate signed by a certificate authority (CA) and private key files. See SSL Overview. To distribute certifications and keys to all hosts in a cluster: 1. Log on to a host that contains the certifications and keys you want to distribute. 2. Start the Administration Tools, as described in Using the Administration Tools. Note: The database does not need to be running when you distribute the certificates and key files. 3. On the Main Menu in the Administration Tools, select Configuration Menu, and click OK. 4. On the Configuration Menu: a. Select Distribute Config Files, and click OK. b. Select SSL Keys, and click OK. 5. Select the database on which you want to distribute the files and click OK. The following appears: HPE Vertica Analytic Database (7.2.x) Page 90 of 101

91 6. [Optional] Modify the fields in the previous screenshot to add the file locations for the server.crt, server.key and root.crt files, and click OK to distribute the files. Admintools sets the parameters SSLCertificate, SSLPrivateKey, and, if applicable, SSLCA. See Security Parameters. If you are upgrading to 7.1, the SSLCertificate and SSLPrivateKey parameters are automatically set by Admintools if you set EnableSSL=1 in the previous version. If your server.crt SSL certificate file includes certificate chain (more than one certificate), Admintools accepts the whole chained certificate. 7. Configure SSL. TLS Authentication Server authentication methods define how clients connect to an Vertica server. Before you define a TLS authentication method, you should understand what type of authentication methods your Vertica server supports. You should also perform any prerequisite tasks. In regards to SSL, your server can operate with: No SSL SSL Server Mode The client does not need certificate or key files. HPE Vertica Analytic Database (7.2.x) Page 91 of 101