LDAP.js Client

Common errors

• Error: connect ECONNREFUSED 127.0.0.1:389

  cause The LDAP server specified in the client URL is not running or is not accessible on the specified host and port.
  fix Verify the LDAP server is running and reachable from the client's network. Check the IP address and port in the `url` option of the LdapClient constructor for correctness.

• Error: LDAP_INVALID_CREDENTIALS

  cause The username (DN) or password provided during the `bind` operation is incorrect or does not have sufficient permissions.
  fix Double-check the credentials used in `client.bind('username', 'password')`. Ensure the DN is correctly formatted and the password matches the LDAP server's record.

• Error: LDAP_NO_SUCH_OBJECT

  cause The Distinguished Name (DN) provided for operations like `add`, `del`, `modify`, or `modifyDN` does not exist on the LDAP server.
  fix Verify the exact DN string for the target entry. Use an LDAP browser or `search` operation to confirm the existence and correct DN of the object before performing modifications or deletions.

Warnings

• gotcha This package (`ldapjs-client`) is distinct from the original `ldapjs` package. The original `ldapjs` is largely unmaintained and has known issues. Always ensure you are installing `ldapjs-client` when seeking an actively maintained LDAP client.
  Fix: Use `npm install ldapjs-client` instead of `npm install ldapjs`.
• gotcha All client operations return Promises. Mixing with traditional callback patterns from older LDAP libraries will lead to unexpected behavior and unhandled promise rejections.
  Fix: Always use `await` with client operations or handle the returned Promise with `.then()` and `.catch()`.
• gotcha The `url` option for `LdapClient` constructor must be a valid LDAP URL containing only the protocol, host, and port (e.g., 'ldap://localhost:389' or 'ldaps://myldap.com:636'). It does not support additional path components or query parameters in the URL string itself.
  Fix: Pass only `proto://host:port` to the `url` option. Other search parameters like `filter`, `scope`, `attributes` should be passed as separate options to the `search` method.

Install

• npm install ldapjs-client npm
• yarn add ldapjs-client yarn
• pnpm add ldapjs-client pnpm

Imports

• LdapClient
  wrong:

  import { LdapClient } from 'ldapjs-client';

  correct:

  import LdapClient from 'ldapjs-client';

  The library primarily exports a default class for ESM. Named import is incorrect.
• LdapClient

  const LdapClient = require('ldapjs-client');

  CommonJS import for Node.js environments.
• client.add
  wrong:

  client.add('cn=foo, o=example', entry, (err, res) => {});

  correct:

  await client.add('cn=foo, o=example', entry);

  All operations are promise-based; direct callbacks are not supported.

Quickstart

This quickstart demonstrates how to create an LDAP client, perform a basic search operation, and properly close the connection using asynchronous promise-based syntax.

import LdapClient from 'ldapjs-client';

const client = new LdapClient({
  url: 'ldap://127.0.0.1:389',
  timeout: 5000 // 5-second timeout for operations
});

async function performLdapSearch() {
  try {
    // Assuming an anonymous bind is allowed for search, or bind first
    // await client.bind('admin_user', process.env.LDAP_PASSWORD ?? '');

    const options = {
      filter: '(&(objectclass=person)(cn=*))', // Search for any person entry
      scope: 'sub',
      attributes: ['dn', 'cn', 'mail']
    };
    console.log('Searching LDAP...');
    const entries = await client.search('o=example', options);
    console.log(`Found ${entries.length} entries:`)
    entries.forEach(entry => console.log(entry.dn, entry.cn, entry.mail));

    // Clean up connection
    await client.unbind();
    await client.destroy();
  } catch (e) {
    console.error('LDAP operation failed:', e.message);
    // Ensure client is destroyed even on error
    if (client) await client.destroy().catch(err => console.error('Error destroying client:', err.message));
  }
}

performLdapSearch();