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

Return to the regular view of this page.

LDAP authentication

Lightweight Directory Access Protocol (LDAP) is an authentication method that works like password authentication.

1: LDAP prerequisites and definitions
2: LDAP authentication parameters
3: TLS for LDAP authentication
4: Authentication fallthrough for LDAP
5: LDAP bind methods

5.1: Workflow for configuring LDAP bind
5.2: Workflow for configuring LDAP search and bind

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.

1 - LDAP prerequisites and definitions

Before you configure LDAP authentication for your Vertica database you must have:.

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:

Parameter name	Description
Host	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.
Common name (CN)	Depending on your LDAP environment, this value can be either the username or the first and last name of the user.
Domain component (DC)	Comma-separated list that contains your organization's domain component broken up into separate values, for example: `dc=vertica, dc=com`
Distinguished name (DN)	domain.com. A DN consists of two DC components, as in "DC=example, DC= com".
Organizational unit (OU)	Unit in the organization with which the user is associated, for example, Vertica Users.
sAMAccountName	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.
UID	A commonly used LDAP account attribute used to store a username.
Bind	LDAP authentication method that allows basic binding using the DN.
Search and bind	LDAP authentication method that must log in to the LDAP server to search on the specified attribute.
Service account	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.
Anonymous binding	Allows a client to connect and search the directory (search and bind) without needing to log in.
`ldapsearch`	A command-line utility to search the LDAP directory. It returns information that you use to configure LDAP search and bind.
basedn	Distinguished name where the directory search should begin.
binddn	Domain name to find in the directory search.
search_attribute	Text to search for to locate the user record. The default is UID.

2 - LDAP authentication 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 Description

Parameter name	Description
`host`	LDAP server URL in the following format: `schema``://host:``optional_port` Where `schema` is one of the following: `ldap`: The connection between Vertica and the LDAP server uses plaintext if TLSMODE of LDAPAuth is `DISABLE`. Set TLSMODE to `ENABLE` or higher for StartTLS (LDAP over TLS). `ldaps`: If the TLSMODE of LDAPAuth is `ENABLE` or higher, the connection between Vertica and the LDAP server uses LDAPS.
ldap_continue	When set to yes, this parameter allows a connection retry when a user not found error occurs during the previous connection attempt. For any other failure error, the system automatically retries the connection.
`starttls`	Whether to request the connection between Vertica and the LDAP server during user authentication to be upgraded to TLS. You must configure the LDAPAuth TLS Configuration before using this parameter. `starttls` can be set to one of the following: `soft`: If the server does not support TLS, use a plaintext connection. This value is equivalent to the `-Z` option in `ldapsearch`. If you use `soft`, Vertica ignores the certificate verification policies of the TLSMODE in the `LDAPAuth` TLS configuration. `hard`: If the LDAP server does not support TLS, reject the connection. 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 and the following error appears: `FATAL 2248: Authentication failed for username "<user_name>"` If `starttls` is not set, whether TLS is requested and required depends on the value of the TLSMODE of the LDAPAuth TLS Configuration.

host

LDAP server URL in the following format:

schema://host:optional_port

Where schema is one of the following:

ldap: The connection between Vertica and the LDAP server uses plaintext if TLSMODE of LDAPAuth is DISABLE. Set TLSMODE to ENABLE or higher for StartTLS (LDAP over TLS).
ldaps: If the TLSMODE of LDAPAuth is ENABLE or higher, the connection between Vertica and the LDAP server uses LDAPS.

ldap_continue

When set to yes, this parameter allows a connection retry when a user not found error occurs during the previous connection attempt.

For any other failure error, the system automatically retries the connection.

starttls

Whether to request the connection between Vertica and the LDAP server during user authentication to be upgraded to TLS. You must configure the LDAPAuth TLS Configuration before using this parameter.

starttls can be set to one of the following:

soft: If the server does not support TLS, use a plaintext connection. This value is equivalent to the -Z option in ldapsearch. If you use soft, Vertica ignores the certificate verification policies of the TLSMODE in the LDAPAuth TLS configuration.
hard: If the LDAP server does not support TLS, reject the connection. 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 and the following error appears:

FATAL 2248: Authentication failed for username "<user_name>"

If starttls is not set, whether TLS is requested and required depends on the value of the TLSMODE of the LDAPAuth TLS Configuration.

LDAP bind parameters

The following parameters create a bind name string, which specifies and uniquely identifies a user to the LDAP server. For details, see Workflow for configuring LDAP bind.

To create a bind name string, you must set one (and only one) of the following:

Both binddn_prefix and binddn_suffix (must be set together)
domain_prefix
email_suffix

For example, if you set binddn_prefix and binddn_suffix, you cannot also set email_suffix. Conversely, if you set email_suffix, you cannot set binddn_prefix and binddn_suffix.

If you do not set a bind parameter, Vertica performs bind and search operations instead of a bind operation.

The following examples use the authentication record v_ldap:

=> CREATE AUTHENTICATION v_ldap METHOD 'ldap' HOST '10.0.0.0/23';

Parameter name	Description
`binddn_prefix`	First half of the bind string. If you set this parameter, you must also set `binddn_suffix`. For example, to construct the bind name `cn=``exampleusername,cn=Users,dc=ExampleDomain,dc=com`: `=> ALTER AUTHENTICATION v_ldap SET binddn_prefix='cn=', binddn_suffix=',cn=Users,dc=ExampleDomain,dc=com';`
`binddn_suffix`	Second half of bind string. If you set this parameter, you must also set `binddn_prefix`. For example, to construct the bind name `cn=exampleusername,``ou=ExampleUsers,dc=example,dc=com`: `=> ALTER AUTHENTICATION v_ldap SET binddn_prefix='cn=', binddn_suffix=',ou=OrgUsers,dc=example,dc=com';`
`domain_prefix`	The domain that contains the user. For example, to construct the bind name `Example``\exampleusername`: `=> ALTER AUTHENTICATION v_ldap SET domain_prefix='Example';`
`email_suffix`	The email domain. For example, to construct the bind name `exampleusername@``example.com` `=> ALTER AUTHENTICATION v_ldap SET email_suffix='example.com';`

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	Description
`basedn`	Base DN for search.
`binddn`	Bind DN. Domain name to find in the directory search.
`bind_password`	Bind password. Required if you specify a binddn.
`search_attribute`	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.

3 - TLS for LDAP authentication

This page covers the LDAPAuth context.

Vertica establishes a connection to an LDAP server in two contexts, and each context has a corresponding TLS Configuration that controls if each connection should use TLS:

LDAPLink: using the LDAPLink service or its dry run functions to synchronize users and groups between Vertica and the LDAP server.
LDAPAuth: when a user with an ldap authentication method attempts to log into Vertica, Vertica attempts to bind the user to a matching user in the LDAP server. If the bind succeeds, Vertica allows the user to log in.

Query TLS_CONFIGURATIONS to view existing TLS Configurations:

=> SELECT * FROM tls_configurations WHERE name IN ('LDAPLink', 'LDAPAuth');
   name   |  owner  | certificate | ca_certificate | cipher_suites |  mode
----------+---------+-------------+----------------+---------------+----------
 LDAPLink | dbadmin | client_cert | ldap_ca        |               | VERIFY_CA
 LDAPAuth | dbadmin | client_cert | ldap_ca        |               | DISABLE
(2 rows)

This page covers the LDAPAuth context. For details on the LDAPLink context, see TLS for LDAP link.

Keep in mind that configuring TLS for LDAP authentication does not encrypt the connection between Vertica and the client with TLS. To configure client-server TLS, see Configuring client-server TLS.

Configuring LDAP authentication

After a client successfully establishes a connection with Vertica, they must authenticate as a user before they can interact with the database. If the user has the ldap authentication method, Vertica connects to the LDAP server to authenticate the user. To configure TLS for this context, use the following procedure.

Setting the LDAPAuth TLS configuration

The LDAPAuth TLS Configuration takes a client certificate and CA certificate created or imported with CREATE CERTIFICATE. Vertica presents the client certificate to the LDAP server for verification by its CA. Vertica uses the CA certificate to verify the LDAP server's certificate.

For details on key and certificate generation, see Generating TLS certificates and keys.

If you want Vertica to verify the LDAP server's certificate before establishing the connection, generate or import a CA certificate and add it to the LDAPAuth TLS CONFIGURATION.

For example, to import the existing CA certificate LDAP_CA.crt:
```
=> \set ldap_ca '\''`cat ldap_ca.crt`'\''
=> CREATE CA CERTIFICATE ldap_ca AS :ldap_ca;
CREATE CERTIFICATE
```
Then, to add the ldap_ca CA certificate to LDAPAuth:
```
ALTER TLS CONFIGURATION LDAPAuth ADD CA CERTIFICATES ldap_ca;
```
If your LDAP server verifies client certificates, you must generate or import a client certificate and its key and add it to the LDAPAuth TLS Configuration. Vertica presents this certificate to the LDAP server for verification by its CA.

For example, to import the existing certificate client.crt (signed by the imported CA) and key client.key:
```
=> \set client_key '\''`cat client.key`'\''
=> CREATE KEY client_key TYPE 'RSA' AS :client_key;
CREATE KEY

=> \set client_cert '\''`cat client.crt`'\''
=> CREATE CERTIFICATE client_cert AS :client_cert SIGNED BY ldap_ca KEY client_key;
CREATE CERTIFICATE
```
Then, to add client_cert to LDAPAuth:
```
=> ALTER TLS CONFIGURATION LDAPAuth CERTIFICATE client_cert;
```
Enable TLS or LDAPS (the exact protocol used depends on the value of host in the AUTHENTICATION object) by setting the TLSMODE to one of the following. TRY_VERIFY or higher requires a CA certificate:
- ENABLE: Enables TLS. Vertica does not check the LDAP server's certificate.
- TRY_VERIFY: Establishes a TLS connection if one of the following is true:
  - The LDAP server presents a valid certificate.
  - The LDAP server doesn't present a certificate.
  If the LDAP server presents an invalid certificate, a plaintext connection is used.
- VERIFY_CA: Connection succeeds if Vertica verifies that the LDAP server's certificate is from a trusted CA. Using this TLSMODE forces all connections without a certificate to use plaintext.
- VERIFY_FULL: Connection succeeds if Vertica verifies that the LDAP server's certificate is from a trusted CA and the cn (Common Name) or subjectAltName attribute matches the hostname or IP address of the LDAP server.
  
  The cn is used for the username, so subjectAltName must match the hostname or IP address of the LDAP server.
Note
The value of TLSMODE only applies to authentication records where the starttls LDAP authentication parameter is set to hard or not set at all. If starttls is set to soft, Vertica establishes a TLS connection without verifying the LDAP server's certificate and falls back to a plaintext connection if the LDAP server does not support TLS. For details, see the next section.

For example:
```
=> ALTER TLS CONFIGURATION LDAPAuth TLSMODE 'verify_ca';
ALTER TLS CONFIGURATION
```

Verify that the LDAPAuthConfigParameter parameter is using the TLS Configuration:

=> SHOW CURRENT LDAPAuthTLSConfig;
  level  |       name        | setting
---------+-------------------+----------
 DEFAULT | LDAPAuthTLSConfig | LDAPAuth
(1 row)

Creating an LDAP authentication record

To view existing authentication records, query CLIENT_AUTH.

For details on the parameters referenced in this procedure, see LDAP authentication parameters.

CREATE an authentication record with an LDAP method.

Syntax for creating an LDAP authentication record:
```
=> CREATE AUTHENTICATION auth_record_name method 'ldap' HOST 'user_connection_source';
```
For example, to create an LDAP authentication record that applies to users that connect from any host:
```
=> CREATE AUTHENTICATION ldap_auth METHOD 'ldap' HOST '0.0.0.0/0';
```
ALTER the authentication record to to set the host and port (optional) of the LDAP server and the domain name (basedn) and bind distinguished name (binddn).
- To use a plaintext connection between Vertica and the LDAP server (disable TLS):
  - Begin the host URL with ldap://.
  - Set the TLSMODE of LDAPAuth to DISABLE and verify that starttls is not set.
- To use StartTLS and reject plaintext connections:
  - Begin the host URL with ldap://.
  - Set the TLSMODE of LDAPAuth to ENABLE or higher. Vertica only verifies the LDAP server's certificate if TLSMODE is set to TRY_VERIFY or higher.
  - Verify that starttls is set to hard or not set.
- To use StartTLS, but still accept a plaintext connection if the LDAP server cannot be upgrade the connection to TLS:
  - Begin the host URL with ldap://.
  - Set starttls to soft and the TLSMODE of LDAPAuth to ENABLE or higher. Vertica does not verify the server's certificate before establishing the connection and ignores the certificate verification policy of the LDAPAuth TLSMODE.
- To use LDAPS:
  - Begin the host URL with ldaps://
  - TLSMODE of LDAPAuth to ENABLE or higher.
This example authentication record searches for users in the active directory orgunit.example.com on an LDAP server with an IP address of 192.0.2.0 on port 5389 and requires a TLS connection to the LDAP server:
```
=> ALTER AUTHENTICATION ldap_auth SET
    host='ldap://192.0.2.0:5389',
    basedn='ou=orgunit,dc=example,dc=com',
    binddn_prefix='cn=',
    binddn_suffix=',ou=orgunit,dc=example,dc=com',
    starttls='hard';
```
The binddn_prefix and binddn_suffix combine to create the full DN. That is, for some Vertica user asmith, 'cn=asmith,ou=orgunit,dc=example,dc=com' is the full DN when Vertica attempts the bind.

To modify the ldap_auth authentication record to request StartTLS, but still accept plaintext connections, set the starttls parameter to soft:
```
=> ALTER AUTHENTICATION ldap_auth SET starttls='soft';
```

Enable the authentication record:

=> ALTER AUTHENTICATION ldap_auth ENABLE;

GRANT the authentication record to a user or role.

For example:
```
=> GRANT AUTHENTICATION ldap_auth TO asmith;
```
In this case, when the user asmith attempts to log in, Vertica constructs the distinguished name 'cn=asmith,ou=orgunit,dc=example,dc=com' from the search base specified in the ldap_auth, connects to the LDAP server, and attempts to bind it to the Vertica user. If the bind succeeds, Vertica allows asmith to log in.

4 - Authentication fallthrough for LDAP

To use multiple search attributes for a single LDAP server or to configure multiple LDAP servers, create a separate authentication record for each search attribute or server and enable authentication fallthrough on each ldap record except the last (in order of priority).

To use multiple search attributes for a single LDAP server or to configure multiple LDAP servers, create a separate authentication record for each search attribute or server and enable authentication fallthrough on each ldap record except the last (in order of priority).

Examples

The following example creates two authentication records, vldap1 and vldap2. Together, they specify that the LDAP server should 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 should then search for a DN with the OU attribute Marketing:

=> CREATE AUTHENTICATION vldap1 method 'ldap' HOST '10.0.0.0/8' FALLTHROUGH;
=> ALTER AUTHENTICATION vldap1 PRIORITY 1;
=> ALTER AUTHENTICATION vldap1
      SET host='ldap://ldap.example.com/search',
      basedn='dc=example,dc=com',
      search_attribute='Sales';
=> GRANT AUTHENTICATION vldap1 to public;

=> CREATE AUTHENTICATION vldap2 method 'ldap' HOST '10.0.0.0/8';
=> ALTER AUTHENTICATION vldap2 PRIORITY 0;
=> ALTER AUTHENTICATION vldap2 SET
      host='ldap://ldap.example.com/search',
      basedn='dc=example,dc=com',
      search_attribute='Marketing';
=> GRANT AUTHENTICATION vldap2 to public;

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

5.1 - Workflow for configuring LDAP bind

To configure your Vertica database to authenticate clients using LDAP bind, follow these steps:.

To configure your Vertica database to authenticate clients using LDAP bind, follow these steps:

Obtain a service account. For information see the LDAP product documentation.You cannot use the service account in the connection parameters for LDAP bind.

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 '172.16.65.177';
=> ALTER AUTHENTICATION ldap1 SET HOST=
   'ldap://172.16.65.10',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)

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 10.10.10.10 -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
result: 0 Success
# numResponses: 2
# numEntries: 1
```
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.0.0.0/0';
=> GRANT AUTHENTICATION v_ldap_bind TO public;
=> ALTER AUTHENTICATION v_ldap_bind SET
host='ldap://10.10.10.10/',
basedn='DC=CompanyCorp,DC=com',
binddn_prefix='cn=',
binddn_suffix=',OU=Vertica Users,DC=CompanyCorp,DC=com';
```

For more information see LDAP Bind Parameters.

5.2 - Workflow for configuring LDAP search and bind

To configure your Vertica database to authenticate clients using LDAP search and bind, follow these steps:.

To configure your Vertica database to authenticate clients using LDAP search and bind, follow these steps:

Obtain a service account. For information see the LDAP product documentation.
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 10.10.10.10 -b 'OU=Vertica Users,DC=CompanyCorp,DC=com' -s sub -D
'CompanyCorp\jsmith' -W '(cn=John*)' cn dn uid sAMAccountName
```

Review the results that ldapsearch returns.The relevant information for search and bind is in bold:

# 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

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 '10.10.10.10';
=> GRANT AUTHENTICATION v_ldap_bind_search TO public;
=> ALTER AUTHENTICATION v_ldap_bind_search SET
host='ldap://10.10.10.10',
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 Bind and Search Parameters