Configure LDAP Authorization

This feature is in preview 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 roles to users based on LDAP group memberships, simplifying access control. When enabled:

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

Prerequisites

Enable LDAP authentication.

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 LDAP authentication. The configuration will include two important LDAP filters:

ldapsearchfilter: Determines which users can authenticate
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. 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 identifier requirements. 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

On the LDAP server, set up test users with memberships in groups that should be synced to CockroachDB users.
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;
Log in to CockroachDB as each test user (refer to Connect to a cluster using LDAP#connect-to-a-cluster-using-ldap).
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 SESSION logging 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 logging directory. 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

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

Get Started

CockroachDB and AI

Feature Overview

Data Resilience

Connect to an Application

Self-Hosted Deployments

Schema Design

Reads and Writes

Stream Data

Cross-Cluster Replication

Multi-Region Capabilities

Optimize Performance

Integrate

Configure LDAP Authorization

Prerequisites

Configuration

Step 1: Enable LDAP authorization

Search filter examples

Group list filter examples

Step 2: Create matching roles

Step 3: Confirm configuration

Troubleshooting

Security considerations

​Prerequisites

​Configuration

​Step 1: Enable LDAP authorization

​Search filter examples

​Group list filter examples

​Step 2: Create matching roles

​Step 3: Confirm configuration

​Troubleshooting

​Security considerations

Prerequisites

Configuration

Step 1: Enable LDAP authorization

Search filter examples

Group list filter examples

Step 2: Create matching roles

Step 3: Confirm configuration

Troubleshooting

Security considerations