Define an LDAP scheme

Hyper-Converged Database (HCD) supports LDAP for:

Authentication: HCD passes through the credentials to the configured LDAP.
Role management: HCD looks up the authenticated user and retrieves a list of LDAP groups and then matches LDAP group names to HCD role names.

Prerequisites

Locate the cassandra.yaml configuration file.

The location of the cassandra.yaml file depends on your installation type:
- Package installations: /etc/hcd/cassandra/cassandra.yaml
- Tarball installations: INSTALL_DIRECTORY/resources/cassandra/conf/cassandra.yaml
Complete Enable HCD Unified Authentication with the following options:
- For authentication, ensure that authenticator.parameters.default_scheme: ldap or authenticator.parameters.additional_schemes: ldap is set in the cassandra.yaml file:
  authenticator: class_name: com.datastax.cassandra.auth.AdvancedAuthenticator parameters: ... scheme: ldap
- For role management, ensure that role_manager.parameters.mode: ldap is set in the cassandra.yaml file:
  role_manager: class_name: com.datastax.cassandra.auth.AdvancedRoleManager parameters: mode: ldap
Ensure that a supported LDAP v3 server is available.

HCD supports:
- Microsoft Active Directory (AD):
  - Windows 2008
  - Windows 2012
- OpenLDAP 2.4.x
- Oracle Directory Server Enterprise Edition 11.1.1.7.0

Configure LDAP parameters

On every node, configure the LDAP parameters in the cassandra.yaml file under the authenticator.parameters section.

For multi-datacenter support, use the nearest available LDAP host.

Set the required LDAP parameters:

Required LDAP parameters
Parameter	Description
`ldap_servers`	Comma-separated list of LDAP servers and optional port numbers in the format `host:_port_`. The default port for unencrypted connections is `389`. The default port for SSL connections is `636`. For example, `ldap1:389,ldap2:389`.
`ldap_user_search_bases`	List of DNs from which to start the recursive search for user entries. For example, `ou=users,dc=example,dc=com`. Active Directory typically uses `CN=Users,DC=example,DC=internal`.
`ldap_user_search_filter`	Filter that identifies a user entry. The default is `(uid={0})`. For Active Directory, use `(sAMAccountName={0})`.

Active Directory does not allow anonymous binds, so ldap_account_dn and ldap_account_password are also required.

Required LDAP parameters for Active Directory

authenticator:
  class_name: com.datastax.cassandra.auth.AdvancedAuthenticator
  parameters:
    ldap_servers: LDAP_HOST:PORT
    ldap_account_dn: ACCOUNT_DN
    ldap_account_password: ACCOUNT_PASSWORD
    ldap_user_search_bases:
      - USER_SEARCH_BASE
    ldap_user_search_filter: (sAMAccountName={0})

Replace the following:

LDAP_HOST: The hostname or IP address of the LDAP server.
PORT: The port that the LDAP server listens on. The default for unencrypted connections is 389. The default for SSL connections is 636.
ACCOUNT_DN: The distinguished name (DN) of the service account used to search for users. For example, cn=lookup_user,cn=users,dc=example,dc=com.
ACCOUNT_PASSWORD: The password for the ACCOUNT_DN account.
USER_SEARCH_BASE: The DN from which to start searching for user entries. For example, cn=users,dc=example,dc=com.

Configure optional parameters as needed:

Optional LDAP parameters — account and search
Parameter	Description
`ldap_account_dn`	DN of the account used to search for users. This account requires only enough permissions to perform searches. Remove this parameter to use an anonymous bind.
`ldap_account_password`	Password for the `ldap_account_dn` account. Requires `ldap_account_dn` to be set.
`ldap_account_anonymous`	Set to `true` to use an anonymous bind. When enabled, this parameter takes precedence over `ldap_account_dn` and `ldap_account_password`.
`ldap_search_retries_max`	Maximum number of retries when a user or group search fails.
`ldap_search_retries_interval`	Interval between search retries.

Optional LDAP parameters — connection
Parameter	Description
`ldap_connection_use_ssl`	Set to `true` to enable SSL connections to the LDAP server. The default is `false`.
`ldap_connection_use_tls`	Set to `true` to enable TLS connections to the LDAP server. The default is `false`.
`ldap_connection_ssl_protocol`	SSL protocol to use when `ldap_connection_use_ssl` is `true`. The default is `TLS`.
`ldap_connection_hostname_verification`	Set to `true` to verify the LDAP server’s hostname during SSL/TLS connections. Requires `ldap_connection_use_ssl` or `ldap_connection_use_tls` to be `true` and a valid `ldap_connection_truststore_path`. The default is `false`.
`ldap_connection_truststore_path`	Path to the truststore file for SSL/TLS certificates.
`ldap_connection_truststore_password`	Password for the truststore.
`ldap_connection_truststore_type`	Type of truststore. The default is `jks`.
`ldap_connection_timeout`	Timeout for LDAP connections. The default is `PT30S` (30 seconds).

Optional LDAP parameters — connection pool
Parameter	Description
`ldap_connection_pool_max_connections`	Maximum size of the connection pool.
`ldap_connection_pool_when_exhausted_block`	Set to `true` to block new requests when the connection pool is exhausted, for the duration set in `ldap_connection_pool_max_wait`. The default is `false`.
`ldap_connection_pool_max_wait`	Maximum time to wait for a connection when the pool is exhausted and `ldap_connection_pool_when_exhausted_block` is `true`.
`ldap_connection_pool_max_idle`	Maximum number of idle connections to keep in the pool.
`ldap_connection_pool_min_idle`	Minimum number of idle connections to keep in the pool.
`ldap_connection_pool_test_on_borrow`	Set to `true` to validate a connection before borrowing it from the pool.
`ldap_connection_pool_test_on_return`	Set to `true` to validate a connection before returning it to the pool.
`ldap_connection_pool_test_while_idle`	Set to `true` to validate idle connections in the pool.
`ldap_connection_pool_time_between_eviction_runs`	Time between runs of the idle connection eviction thread.
`ldap_connection_pool_num_tests_per_eviction_run`	Number of connections to test per eviction run.
`ldap_connection_pool_min_evictable_idle_time`	Minimum time a connection must be idle before the eviction thread considers removing it.
`ldap_connection_pool_soft_min_evictable_idle_time`	Minimum time a connection must be idle before the eviction thread considers removing it, provided the pool has more than `ldap_connection_pool_min_idle` connections.

Optional LDAP parameters — caching
Parameter	Description
`ldap_caching_user_validity`	Duration for which HCD caches user search results. Set to `0` to disable. The cache is disabled by default. Changes to user data on the LDAP server do not take effect in HCD until the cache expires.
`ldap_caching_user_update_interval`	Interval at which HCD asynchronously refreshes cached user entries before they expire.
`ldap_caching_user_max_entries`	Maximum number of user entries to hold in the cache.
`ldap_caching_group_validity`	Duration for which HCD caches group search results. Set to `0` to disable. The cache is disabled by default. Changes to group data on the LDAP server do not take effect in HCD until the cache expires.
`ldap_caching_group_update_interval`	Interval at which HCD asynchronously refreshes cached group entries before they expire.
`ldap_caching_group_max_entries`	Maximum number of group entries to hold in the cache.
`ldap_caching_credentials_validity`	Duration for which HCD caches user credentials locally. Caching reduces repeated binds to the LDAP server and improves post-authentication performance. Set to `0` to disable. The cache is disabled by default. Changes to credentials on the LDAP server do not take effect in HCD until the cache expires.
`ldap_caching_credentials_update_interval`	Interval at which HCD asynchronously refreshes cached credentials before they expire.
`ldap_caching_credentials_max_entries`	Maximum number of credential entries to hold in the cache.

Optional LDAP parameters — failover
Parameter	Description
`ldap_failover_retry_count`	Number of times HCD retries a failed LDAP server before marking it as unavailable.
`ldap_failover_quarantine_opening_threshold`	Number of failures required to quarantine an LDAP server.
`ldap_failover_quarantine_opening_interval`	Interval during which failures are counted toward the quarantine threshold.
`ldap_failover_quarantine_close_threshold`	Number of successes required to bring a quarantined LDAP server back into service.
`ldap_failover_quarantine_close_interval`	Interval during which successes are counted toward the close threshold.

For LDAP role management, choose one of the following:

Option 1. Configure HCD to get a list of groups from an attribute of the user entry:

  parameters:
    ldap_group_search_type: memberof_search
  ldap_group_search_memberof_attribute: memberof

memberof is the attribute that contains a list of groups in the default Microsoft Active Directory LDAP scheme. OpenLDAP does not include a memberof attribute by default.

Parameter Setting Description

ldap_group_search_type

memberof_search

Reads group membership from an attribute on the user entry. HCD assigns roles that exactly match any group name in that attribute.

Unmatched groups are ignored.

ldap_group_search_memberof_attribute

memberof

Attribute on the user entry that lists the DNs of groups the user belongs to.

To use an optimized single-request search for all parent groups including inherited ones, also configure the following optional parameters:

Optional memberof search — all-parents optimization
Parameter	Description
`ldap_group_search_all_parents_memberof_attribute`	Attribute that lists all parent groups transitively, for LDAP servers that support this mechanism. For example, Oracle LDAP supports this with the `isMemberOf` attribute. The default is `isMemberOf`.
`ldap_group_search_all_parents_search_type`	Set to `memberof_search` or `directory_search` to enable the all-parents optimization. Leave empty to disable this mechanism when the LDAP server does not support it.
`ldap_group_search_all_parents_search_filter`	Filter used to find all groups a role belongs to in a single request. For example, Active Directory supports `(member:1.2.840.113556.1.4.1941:={0})`.

Option 2. Configure HCD to search group objects from the search base and return the groups that contain the user:

  parameters:
    ldap_group_search_type: directory_search
    ldap_group_search_bases:
      - GROUP_SEARCH_BASE
    ldap_group_search_filter: (uniquemember={0})
    ldap_group_search_name_attribute: cn

Replace GROUP_SEARCH_BASE with the DN from which to start searching for group objects. For example, cn=internal,ou=group,dc=example,dc=com.

uniquemember is the attribute that lists users in a group in the default Microsoft Active Directory LDAP scheme.

Parameter Setting Description

ldap_group_search_type

directory_search

Searches for group objects using ldap_group_search_bases and returns the groups that contain the user.

ldap_group_search_bases

GROUP_SEARCH_BASE

List of DNs from which to start the recursive search for group objects.

ldap_group_search_filter

(uniquemember={0})

Filter that matches users within a group. In most LDAP services, this attribute is uniquemember.

ldap_group_search_name_attribute

cn

Attribute that contains the group name that HCD matches to a role. The group name must exactly match the HCD role name, including case.

Unmatched groups are ignored.

Perform a rolling restart to implement the changes.

When adding LDAP to and authentication enabled HCD environment, DataStax recommends setting up roles for LDAP users and groups before restarting.

Use Apache Cassandra® open-source authenticators

HCD provides AdvancedAuthenticator with built-in LDAP support. However, you can use Cassandra’s open-source authenticators if you need compatibility with existing Cassandra configurations or custom authenticator implementations.

Consider using Cassandra’s open-source authenticators when you:

Migrate from Cassandra and want to reuse existing LDAP configurations.
Have custom authenticator implementations built on Cassandra’s IAuthenticator interface.
Need specific Cassandra authenticator behavior for compatibility requirements.

Compare with AdvancedAuthenticator

Before you choose open-source authenticators, review the advantages of HCD’s AdvancedAuthenticator:

Multiple authentication schemes: Supports internal, LDAP, and OIDC authentication simultaneously
Advanced role management: Provides automatic LDAP group-to-role mapping with AdvancedRoleManager
Unified configuration: Centralizes all authentication settings in one location
Enhanced security: Offers additional configuration options and security controls
Modern standards: Includes built-in support for OIDC and modern authentication protocols

Configure open-source authenticators

To use Cassandra’s open-source authenticators, you must configure all three security components together:

authenticator: Your chosen Cassandra authenticator class
authorizer: org.apache.cassandra.auth.CassandraAuthorizer
role_manager: org.apache.cassandra.auth.CassandraRoleManager

To configure Cassandra’s open-source authenticators, do the following:

Open your cassandra.yaml file.

Set the authenticator, authorizer, and role_manager to use Cassandra classes:

# Use Apache Cassandra's PasswordAuthenticator
authenticator: org.apache.cassandra.auth.PasswordAuthenticator

# Or use your custom LDAP authenticator class
# authenticator: com.example.CustomLDAPAuthenticator

# Must use CassandraAuthorizer with open-source authenticators
authorizer: org.apache.cassandra.auth.CassandraAuthorizer

# Must use CassandraRoleManager with open-source PasswordAuthenticator or a custom LDAP authenticator class.
role_manager: org.apache.cassandra.auth.CassandraRoleManager

Increase the system_auth keyspace replication factor. For more information, see Configure the security keyspaces replication factors.
Perform a rolling restart of all nodes in the cluster.