---
title: "Complete LDAP setup example for Rocket Chat"
slug: "ldap-setup"
description: "Follow this guide to set up LDAP in Rocket Chat. Enable secure login, scalable identity management, and compliance-ready communications."
updated: 2026-10-26T16:49:40Z
published: 2026-10-26T16:49:40Z
canonical: "docs.rocket.chat/ldap-setup"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rocket.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# LDAP Setup Example

![](https://cdn.us.document360.io/6ae79a05-7252-45d0-96e8-8f375e07b1b2/Images/Documentation/Premium(1).svg)

> [!WARNING]
> From Rocket.Chat 9.0.0, LDAP is available on Starter workspaces and on all premium plans (Commercial, Government, and Defense). It is not available on Community workspaces. See [Our Plans](/v1/docs/our-plans) for details.

## Prerequisites

Before you begin, ensure the following are installed on your machine:

- **Docker**: Used to deploy the OpenLDAP server locally.
- **An LDAP management tool**: This guide uses Apache Directory Studio (ADS), but alternatives like phpLDAPadmin are also suitable.
- **A local Rocket.Chat workspace**: Required for testing LDAP authentication and synchronization.

## Step 1: Run an LDAP server

Rocket.Chat supports connecting to both OpenLDAP and Active Directory servers for authentication and directory synchronization.

In this section, we’ll deploy an OpenLDAP server using Docker. To create the Docker Compose file:

1. Navigate to your preferred working directory.
2. Create a file named `docker-compose.yml`.
3. Add the following configuration:

```yaml
services:
  openldap:
    image: osixia/openldap:1.3.0
    container_name: rc-openldap
    environment:
      LDAP_LOG_LEVEL: "256"
      LDAP_ORGANISATION: "rcldap"
      LDAP_DOMAIN: "rcldap.com.br"
      LDAP_ADMIN_PASSWORD: "admin"
    volumes:
      - /var/lib/ldap
      - /etc/ldap/slapd.d
      - /container/service/slapd/assets/certs/
    ports:
      - "389:389"
      - "636:636"
```

## Step 2: Connect to the LDAP server

Once the container is running, you can connect to the LDAP server using your preferred LDAP management tool (such as Apache Directory Studio).

### Start the container

If you haven’t already started the service, run:

```bash
docker compose up -d
```

This deploys the OpenLDAP server locally:

- **LDAP:** `ldap://localhost:389`
- **LDAPS:** `ldaps://localhost:636` (requires SSL configuration)

### Create a new LDAP connection

Open your LDAP management tool and create a new connection.

In **Apache Directory Studio**, navigate to the **Connections** view and select **New Connection**.

Use the following configuration:

- **Host name:** `localhost`
- **Port:** `389`
- **Encryption method:** No encryption (for this example)
- **Authentication method:** Simple Authentication
- **Bind DN (Admin user):** `cn=admin,dc=rcldap,dc=com,dc=br`
- **Bind password:** `admin`

> [!NOTE]
> The Bind DN is automatically generated based on the `LDAP_DOMAIN` and `LDAP_ADMIN_PASSWORD` values defined in the `docker-compose.yml` file.

### Authentication configuration (Apache Directory Studio)

Your authentication screen should resemble the following:

- Authentication Method: **Simple Authentication**
- Bind DN or user: `cn=admin,dc=rcldap,dc=com,dc=br`
- Password: `admin`

![](https://cdn.us.document360.io/6ae79a05-7252-45d0-96e8-8f375e07b1b2/Images/Documentation/ADS connection setup.png)

After entering the credentials:

1. Click **Check Authentication** to verify the connection.
2. Click **Finish** to complete the setup.

If the configuration is correct, the LDAP server will appear in the Connections panel, and you will be able to browse the directory structure.

### Verify the LDAP directory structure

After successfully connecting to the LDAP server through Apache Directory Studio (ADS), the LDAP tree structure should be displayed.

At this stage, the directory contains:

- The standard domain: `dc=rcldap,dc=com,dc=br`
- The administrator account: `cn=admin`

Your LDAP browser should show the domain entry with the admin user nested under it, as illustrated below.

![](https://cdn.us.document360.io/6ae79a05-7252-45d0-96e8-8f375e07b1b2/Images/Documentation/LDAP Server tree structure result before full setup.png)

ADS is now ready to populate the LDAP server with groups and users that can connect to Rocket.Chat.

---

## Add organizational units, users, and groups

For this example use case, all users and organizational units will be added under the default domain created during the LDAP server setup.

You can refer to the Oracle [LDAP Security Fundamentals](https://docs.oracle.com/cd/E79533_01/VSMGU/ldap001.htm) documentation for additional information about Users, Groups, and Organizational Units in LDAP servers.

After creating all organizational units, groups, and users as described in the following steps, your LDAP tree structure should look like this:

![](https://cdn.us.document360.io/6ae79a05-7252-45d0-96e8-8f375e07b1b2/Images/Documentation/LDAP Server tree structure result after setup.png)

### Organizational units

To add new organizational units within the default domain, right-click the domain element (`dc=rcldap,dc=com,dc=br`) in the tree structure, then select **New → New Entry** and follow the steps below.

Create two organizational units using the `organizationalUnit` object class:

- **Users**
- **Groups**

![](https://cdn.us.document360.io/6ae79a05-7252-45d0-96e8-8f375e07b1b2/Images/Documentation/ADS steps for adding organizational units.png)

### Users

For this example, users must be created under the **Users** organizational unit.

Right-click the `ou=Users` element in the tree structure, then select **New → New Entry** and follow the steps shown below.

Use the `inetOrgPerson` object class.

![](https://cdn.us.document360.io/6ae79a05-7252-45d0-96e8-8f375e07b1b2/Images/Documentation/ADS steps for adding users.png)

### Groups

For this example, only users who are members of a specific LDAP group will be allowed to log in to Rocket.Chat.

To configure this, create a new **RCUsers** group under the **Groups** organizational unit. Right-click the `ou=Groups` element in the tree structure, then select **New → New Entry** and follow the steps shown below.

Use the `groupOfNames` object class. In the final step, browse to the user you previously created and assign it to the group by adding it to the `member` attribute.

![](https://cdn.us.document360.io/6ae79a05-7252-45d0-96e8-8f375e07b1b2/Images/Documentation/ADS steps for adding groups.png)

Additional members can be added later by creating new `member` attributes in the existing **RCUsers** group.

---

## Configure LDAP in Rocket.Chat

After setting up and populating your LDAP server, the next step is to configure Rocket.Chat to connect to it.

In this section, you will:

- Configure the LDAP connection
- Set up authentication credentials
- Define user and group search filters
- (Optional) Configure SSL for secure connections

### Connection

Go to **Manage** ![Screenshot 2025-12-23 130522.png](https://cdn.us.document360.io/6ae79a05-7252-45d0-96e8-8f375e07b1b2/Images/Documentation/Screenshot%202025-12-23%20130522.png) **→ Workspace → Settings → LDAP → Connection**, enable LDAP, and configure the following settings:

- **Server Type:** `Other`
- **Host:** `localhost`
- **Port:** `389`

Save the changes and click **Test Connection** in the upper-right corner of the screen. A **“LDAP Connection Successful”** toast message should appear.

### Authentication

Navigate to **LDAP → Connection → Authentication** and configure:

- **User DN:** `cn=admin,dc=rcldap,dc=com,dc=br`
- **Password:** `admin`

### Search filter

Go to **LDAP → User Search → Search Filter** and configure the following:

- **Base DN:** `dc=rcldap,dc=com,dc=br`
- **Filter:** `(objectclass=inetOrgPerson)`
- **Scope:** `sub`
- **Search Field:** `uid`
- **Search Page Size:** `250`
- **Search Size Limit:** `1000`

After completing this step, you should be able to search LDAP users in your workspace using the configured connection. Click **Test LDAP Search** in the upper-right corner of the screen, enter a user's `uid`, and confirm that a success toast message is displayed.

### Group filter

Configuring this section restricts access to Rocket.Chat to members of the **RCUsers** group created in the previous steps.

Go to **LDAP → User Search → Group Filter**, enable **Enable LDAP User Group Filter**, and configure:

- **Group ObjectClass:** `groupOfNames`
- **Group ID Attribute:** `cn`
- **Group Member Attribute:** `member`
- **Group Member Format:** `#{userdn}`
- **Group name:** `RCUsers`

After this configuration, LDAP users should be able to log in to Rocket.Chat using their `uid` or `mail` and the password set in the LDAP server.

To sync users that exist in your LDAP directory but not in Rocket.Chat, enable **Background Sync Import New Users** under **LDAP → Premium → Background Sync**, then click **Sync Now** to import them into your workspace.

### Log in with an email address

Rocket.Chat allows workspace owners to choose which LDAP fields are used to identify users during authentication.

By default, the `uid` field is used, allowing users to log in with their username and password. This can be customized under **LDAP → User Search → Search Filter → Search Field** to support different login formats:

- Log in with either email address or username: `uid,mail`
- Log in with email address only: `mail`

### LDAP SSL connection

When LDAP is enabled, the login form authenticates users via LDAP instead of the internal account system.

In this example, Stunnel is used to create a secure connection to the LDAP server.

Create a new configuration file at `/etc/stunnel/ldaps.conf` with the following content:

```bash
options = NO_SSLv2

[ldaps]
client = yes
accept = 389
connect = your_ldap_server.com:636
```

To enable Stunnel automatic startup, change the `ENABLED` variable in `/etc/default/stunnel4` to `1`:

```bash
# Change to one to enable stunnel automatic startup
ENABLED=1
```

Finally, in your Rocket.Chat workspace, go to **Manage → Workspace → Settings → LDAP** and configure:

- **LDAP host:** `localhost`
- **LDAP port:** `389`

By adjusting these settings according to your environment, you can ensure a secure and efficient configuration.

This concludes the LDAP configuration section, covering connection and user management settings in Rocket.Chat.