Configure LDAP Authorization

This feature is in and subject to change. To share feedback and/or issues, contact Support.

If you manage users through a service compatible with the Lightweight Directory Access Protocol (LDAP), such as Active Directory or Microsoft Entra ID, you can configure CockroachDB to automatically assign to users based on LDAP group memberships, simplifying access control.

When enabled:

1. When a client connects to the cluster using LDAP, the cluster looks up the user’s group membership in the LDAP service.
2. Each LDAP group is mapped to a cluster role using the group’s Common Name (CN) in the LDAP service.
3. The user is granted each corresponding role, and roles that no longer match the user’s groups are revoked.

Prerequisites

• Enable .

Configuration

Before you begin, it may be useful to enable authentication logging, which can help you confirm sucessful configuration or troubleshoot issues. For details, refer to Troubleshooting.

Step 1: Enable LDAP Authorization

Add the ldapgrouplistfilter parameter to the HBA configuration that you enabled for . The configuration will include two important LDAP filters:

1. ldapsearchfilter: Determines which users can authenticate
2. ldapgrouplistfilter: Defines which groups should be considered for authorization

Here’s a basic example:

SET CLUSTER SETTING server.host_based_authentication.configuration = '
host    all    all    all    ldap    ldapserver=ldap.example.com
    ldapport=636
    "ldapbasedn=ou=users,dc=example,dc=com"
    "ldapbinddn=cn=readonly,dc=example,dc=com"
    ldapbindpasswd=readonly_password
    ldapsearchattribute=uid
    "ldapsearchfilter=(memberof=cn=cockroachdb_users,ou=groups,dc=example,dc=com)"
    "ldapgrouplistfilter=(objectClass=groupOfNames)"';

For more precise control, you can configure these filters to match your security requirements. Refer to the examples below, and further documentation on LDAP syntax filters.

Search filter examples

To restrict authentication to members of specific groups:

-- Users must be members of either the database users group or the analytics team
"ldapsearchfilter=(|(memberof=cn=cockroachdb_users,ou=groups,dc=example,dc=com)(memberof=cn=analytics_team,ou=groups,dc=example,dc=com))"

Group List filter examples

The ldapgrouplistfilter configuration varies by LDAP server type:

-- For Azure Active Directory:
"ldapgrouplistfilter=(objectCategory=CN=Group,CN=Schema,CN=Configuration,DC=example,DC=com)"

-- For OpenLDAP (using groupOfNames):
"ldapgrouplistfilter=(objectClass=groupOfNames)"

-- For OpenLDAP (using groupOfUniqueNames):
"ldapgrouplistfilter=(objectClass=groupOfUniqueNames)"

For enhanced security, restrict the groups that can be mapped to CockroachDB roles:

-- Only map specific groups to CockroachDB roles
"ldapgrouplistfilter=(|(cn=crdb_analysts)(cn=crdb_developers))"

We recommend that you explicitly specify which groups should be mapped to CockroachDB roles rather than using broader filters. This ensures that only intended groups are granted database access.

Step 2: Create matching roles

Create CockroachDB roles that match your LDAP group names and grant appropriate privileges to each role. Remember that role names must comply with CockroachDB’s .

For example, if you’ve configured the group filter to allow crdb_analysts and crdb_developers:

-- Create role for analysts
CREATE ROLE crdb_analysts;
GRANT SELECT ON DATABASE analytics TO crdb_analysts;

-- Create role for developers
CREATE ROLE crdb_developers;
GRANT ALL ON DATABASE app TO crdb_developers;

Step 3: Confirm configuration

1. On the LDAP server, set up test users with memberships in groups that should be synced to CockroachDB users.

2. When logged in as an admin to CockroachDB, create the matching test users (note the omission of a password; this will be validated against the user’s LDAP password):

   CREATE ROLE username1 LOGIN;
   CREATE ROLE username2 LOGIN;
   CREATE ROLE username3 LOGIN;
   

3. Log in to CockroachDB as each test user (refer to #connect-to-a-cluster-using-ldap).

4. Using your admin credentials, log in to the CockroachDB SQL shell and run SHOW ROLES; to view and verify users and their role assignments.

Troubleshooting

Enable to preserve data that will help troubleshoot LDAP issues:

SET CLUSTER SETTING server.auth_log.sql_sessions.enabled = true;

Once all functionality is configured and tested successfully, we recommend disabling session logging to conserve system resources.

To view the logs, open cockroach-session.log from your .

Potential issues to investigate may pertain to:

• Network connectivity to the LDAP server.
• Incorrect bind DN or password.
• Search filter not matching the intended users.
• TLS certificates.
• Missing or mismatched role names.

Security Considerations

1. Always keep a backup authentication method (like password) for administrative users.
2. Use LDAPS (LDAP over TLS) in production environments.
3. Use a restricted service account for directory searches.
4. Regularly audit LDAP group memberships.
5. Monitor authentication logs for unusual patterns.