Configuring LDAP authentication

Steps for configuring DSE to use an external LDAP server to enable LDAP authentication.

LDAP authentication is enabled by configuring DataStax Enterprise to use an external LDAP server. When using LDAP authentication, use DataStax recommends using the DSE Role Manager with LDAP roles.

The following rules apply when LDAP groups are used:
  • Each LDAP user must map to an LDAP group.
  • Each LDAP group must be mapped to an internal Cassandra role that was created with the CREATE ROLE command.
    Roles in LDAP are case sensitive. Cassandra roles are created with lower case. To retain the case of LDAP groups when you create the Cassandra role, use single quotation marks. For example, to create the Admin group:
    CREATE ROLE 'Admin'
    Otherwise, CREATE ROLE Admin creates the lower case admin role.
  • Each role must have the appropriate login privileges.
  • Any users mapped to the LDAP group can authenticate with the cluster.
The location of the cassandra.yaml file depends on the type of installation:
Installer-Services /etc/dse/cassandra/cassandra.yaml
Package installations /etc/dse/cassandra/cassandra.yaml
Installer-No Services install_location/resources/cassandra/conf/cassandra.yaml
Tarball installations install_location/resources/cassandra/conf/cassandra.yaml
The location of the dse.yaml file depends on the type of installation:
Installer-Services /etc/dse/dse.yaml
Package installations /etc/dse/dse.yaml
Installer-No Services install_location/resources/dse/conf/dse.yaml
Tarball installations install_location/resources/dse/conf/dse.yaml

Prerequisites

You must have a properly configured LDAP v3 server running. The supported LDAP servers are:

  • Microsoft Active Directory:
    • Windows 2008
    • Windows 2012
  • OpenLDAP 2.4.x
  • Oracle Directory Server Enterprise Edition 11.1.1.7.0

Procedure

  1. Complete the authentication configuration as described in Configuring authentication to ensure that ldap is specified for default_scheme or other_schemes.
  2. In the dse.yaml file, set the configuration for your LDAP server.
    Option Description
    server_host The host name of the LDAP server.
    server_port The port on which the LDAP server listens. The default port for unencrypted connections is 389.

    The default SSL port for LDAP is 636.

    search_dn The username of the user that is used to search for other users on the LDAP server. If not present, an anonymous bind is used for the search.
    search_password The password of the search_dn user.
    use_ssl Set to true to enable SSL connections to the LDAP server. If set to true, you might need to change server_port to the SSL port of the LDAP server. The default value is false.
    use_tls Set to true to enable TLS connections to the LDAP server. If set to true, change the server_port to the TLS port of the LDAP server. The default value is false.
    truststore_path The path to the truststore for SSL certificates.
    truststore_password The password to access the trust store.
    truststore_type The type of truststore. The default value is jks.
    user_search_base The search base for your domain, used to look up users. Set the ou and dc elements for your LDAP domain. Typically this is set to ou=users,dc=domain,dc=top_level_domain. For example, ou=users,dc=example,dc=com.

    Active Directory uses a different search base, typically CN=search,CN=Users,DC=ActDir_domname,DC=internal. For example, CN=search,CN=Users,DC=example-sales,DC=internal.

    user_search_filter The search filter for looking up user names. The default setting is (uid={0}).

    When using Active Directory set the filter to (sAMAccountName={0}).

    user_memberof_attribute The attribute on the user entry that contains group membership information.
    group_search_type Define how group membership is determined for a user. Choose from one of the following values:
    • directory_search - Filters the results by doing a subtree search of group_search_base to find groups that match the group_search_filter. (Default)
    • memberof_search - Get groups from the memberof attribute of the user. The directory server must have memberof support.
    More efficient, the memberof_search relies on the directory server being configured to return a memberof attribute in user searches that contain the groups that a user belongs to.

    The memberof_search requires only a single round trip to the directory server to get user information and group information. A memberof_search uses the user_memberof_attribute to looks for groups on the user entry. The group names are then resolved using the attribute defined in the group_name_attribute.

    group_search_base The unique distinguished name (DN) of the group from which to base the group membership search on.
    group_search_filter The LDAP group to filter the search on. Default: (uniquemember={0})The group_search_filter is combined with a user DN before the search starts. For the following options:
    ldap_options:
        group_search_type: directory_search
        group_search_base: ou=groups,dc=example,dc=com
        group_search_filter: (uniquemember={0})
    Looking for a user cn=test,ou=users,dc=example,dc=com, the search finds groups that have this user as a unique member.
    group_name_attribute The attribute in the group entry that holds the LDAP group name. Default: cn
    credentials_validity_in_ms The duration period in milliseconds for the credential cache. To disable the cache, set it to 0. The cache is disabled by default.

    With the cache enabled, DataStax Enterprise stores the user credentials locally during the specified time. Binding to a remote LDAP server takes time and resources, so enabling a credential cache usually results in faster performance following the initial authentication phase. Changes in user credentials on the LDAP server are not reflected in DataStax Enterprise during the cache period.

    search_validity_in_seconds The duration period in milliseconds for the search cache. To disable the cache, set it to 0. The cache is disabled by default.

    Enabling a search cache improves performance by reducing the number of requests that are sent to the LDAP server. Changes in user data on the LDAP server are not reflected during the cache period.

    connection_pool The configuration settings for the connection pool for making LDAP requests.
    max_active The maximum number of active connections to the LDAP server. The default value is 8.
    max_idle The maximum number of idle connections in the pool awaiting requests. The default value is 8.
    ldap_options:
        server_host: localhost
        server_port: 389
        search_dn: cn=Admin
        search_password: secret
        use_ssl: false
        use_tls: false
        truststore_path:
        truststore_password:
        truststore_type: jks
        user_search_base: ou=users,dc=example,dc=com
        user_search_filter: (uid={0})
        user_memberof_attribute: memberof
        group_search_type: directory_search#
        group_search_base:#
        group_search_filter: (uniquemember={0})
        group_name_attribute: cn
        credentials_validity_in_ms: 0
        connection_pool:
            max_active: 8
            max_idle: 8
    Tip: To tune or test the LDAP connection see Cassandra Advanced Startup parameters /en/cassandra/3.0/cassandra/tools/toolsCUtility.html#toolsCUtility__advanced.
  3. Start cqlsh and login using the superuser name and password.
    DataStax Enterprise automatically creates a cassandra superuser but it is unlikely that this user will be available on the remote LDAP service. Use the following steps to create a superuser and other users in Cassandra.
    ./cqlsh -u cassandra -p cassandra
  4. DataStax Enterprise automatically creates a cassandra superuser but it is unlikely that this user will be available on the remote LDAP service. Create a superuser and other roles in Cassandra.
  5. Login as the new superuser.
  6. If it has not been done already, change the default cassandra user.
    Note: This step is highly recommended to improve the security of DataStax Enterprise.
  7. Repeat these steps on each node in the cluster.