OpenText Analytics Database 26.2.x – LDAP authentication

Security-and-Authentication: LDAP prerequisites and definitions

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisites

Before you configure LDAP authentication for your OpenText™ Analytics Database you must have:

IP address and host name for the LDAP server. The database supports IPv4 and IPv6 addresses.
Your organization's Active Directory information.
A service account for search and bind.
Administrative access to your 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. The database 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, OpenText 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.

Security-and-Authentication: LDAP authentication parameters

Mon, 01 Jan 0001 00:00:00 +0000

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 OpenText™ Analytics Database 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 the database 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 the database 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`, the database 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 OpenText™ Analytics Database 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 the database 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 the database 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, the database 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, the database 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, the database performs an anonymous search.

Security-and-Authentication: TLS for LDAP authentication

Mon, 01 Jan 0001 00:00:00 +0000

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 OpenText™ Analytics Database 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 the database, they must authenticate as a user before they can interact with the database. If the user has the ldap authentication method, the database 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. The database presents the client certificate to the LDAP server for verification by its CA. The database 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 the database 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. The database 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, the database 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 the database 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. The database 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. The database 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 database user asmith, 'cn=asmith,ou=orgunit,dc=example,dc=com' is the full DN when the database 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, the database 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 database user. If the bind succeeds, the database allows asmith to log in.

Security-and-Authentication: Authentication fallthrough for LDAP

Mon, 01 Jan 0001 00:00:00 +0000

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;

Security-and-Authentication: LDAP bind methods

Mon, 01 Jan 0001 00:00:00 +0000

There are two LDAP methods that you use to authenticate your OpenText™ Analytics Database against an LDAP server.

Bind—Use LDAP bind when the database 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 the database 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.

OpenText Analytics Database 26.2.x – LDAP authentication

Security-and-Authentication: LDAP prerequisites and definitions

Prerequisites

Definitions

Security-and-Authentication: LDAP authentication parameters

General LDAP parameters

LDAP bind parameters

LDAP search and bind parameters

Security-and-Authentication: TLS for LDAP authentication

Configuring LDAP authentication

Setting the LDAPAuth TLS configuration

Note

Creating an LDAP authentication record

Security-and-Authentication: Authentication fallthrough for LDAP

Examples

Security-and-Authentication: LDAP bind methods

LDAP anonymous binding