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

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.