LDAP Server Mock

Common errors

• Error: Unknown option '--conf' or 'filePath' is not a valid value for '--conf'

  cause Incorrect command-line argument format for `--conf` or `--database` after v6.0.0.
  fix Use quoted values for file paths: `npx ldap-server-mock --conf="./conf.json" --database="./users.json"`.

• LDAP search operation returns no results, but I expect a user to be found.

  cause The search filter logic in v5.0.0 and later is more stringent, requiring all filter conditions to match, or user attributes are not correctly structured under the `attributes` property since v6.0.0.
  fix Verify that your mock user objects conform to the v6.0.0 structure (all non-DN attributes under an `attributes` object) and that their attributes satisfy all conditions in your LDAP search filter.

• Error: The 'dn' attribute is missing from an LDAP user object.

  cause An `LdapUser` object in your configuration is missing the mandatory `dn` (Distinguished Name) property.
  fix Ensure every user object in your `users.json` file or `LdapUser[]` array has a `dn` property with a valid LDAP distinguished name string.

Warnings

• breaking The command-line arguments `--conf` and `--database` now require values to be quoted (e.g., `--conf="filePath"` instead of `--conf filePath`).
  Fix: Ensure all command-line options containing file paths are correctly quoted, like `npx ldap-server-mock --conf="/path/to/conf.json" --database="/path/to/users.json"`.
• breaking User configuration JSON structure has changed. All user attributes, except `dn`, must now be nested under an `attributes` property within each user object. This is due to the adoption of `ldapjs` filters.
  Fix: Update your `users.json` or `LdapUser[]` array to move all non-DN attributes into an `attributes` object. For example, `{ dn: 'cn=user', cn: 'value' }` becomes `{ dn: 'cn=user', attributes: { cn: 'value' } }`.
• breaking The search filter logic has changed. Previously, only the `userLoginAttribute` was used to match a user, ignoring other aspects of the search query. Now, the server considers all aspects of the `searchFilter` property, which may require adjustments to user attributes in your database to ensure matches.
  Fix: Review your `searchFilter` configurations and ensure that the attributes of your mock users in the database (`users.json` or `LdapUser[]`) accurately reflect all criteria specified in your search queries.
• breaking Dropped support for older Node.js and NPM versions. The package now requires Node.js >=16.3.0 and NPM >=7.15.1.
  Fix: Upgrade your Node.js installation to version 16.3.0 or higher, and ensure NPM is at version 7.15.1 or higher.
• breaking Relative paths for `--conf` and `--database` options are now resolved relative to the *current working directory* where the command is executed, rather than relative to the `ldap-server-mock` module's installation directory.
  Fix: When using relative paths with `--conf` or `--database`, ensure they are correct with respect to the directory from which you are running the `npx ldap-server-mock` command.

Install

• npm install ldap-server-mock npm
• yarn add ldap-server-mock yarn
• pnpm add ldap-server-mock pnpm

Imports

• LdapServerMock
  wrong:

  const { LdapServerMock } = require('ldap-server-mock');

  correct:

  import { LdapServerMock } from 'ldap-server-mock';

  The library primarily targets ESM environments and ships TypeScript types. Use named imports for the main class.
• LdapUser

  import { LdapUser } from 'ldap-server-mock';

  Import the `LdapUser` type for type-checking when defining your mock user arrays.
• LdapServerMockConfiguration

  import { LdapServerMockConfiguration } from 'ldap-server-mock';

  Import the `LdapServerMockConfiguration` type for configuring the mock server via the API.

Quickstart

This quickstart demonstrates how to programmatically start and stop an `LdapServerMock` instance, configure its users and server settings, and optionally enable TLS with dummy certificates. It defines two mock users and sets up a server on port 3004, then starts and stops it after a short delay.

import * as fs from 'node:fs/promises';
import { LdapServerMock } from 'ldap-server-mock';

async function main() {
  // Define your mock LDAP users
  const ldapUsers = [
    {
      dn: 'cn=testuser,dc=example,dc=com',
      attributes: {
        objectClass: 'person',
        cn: 'testuser',
        uid: 'testuser',
        mail: 'testuser@example.com'
      }
    },
    {
      dn: 'cn=anotheruser,dc=example,dc=com',
      attributes: {
        objectClass: 'person',
        cn: 'anotheruser',
        uid: 'anotheruser',
        mail: 'anotheruser@example.com'
      }
    }
  ];

  // Configure the LDAP server mock
  const serverConfiguration = {
    port: 3004,
    searchBase: 'dc=example,dc=com'
  };

  // For a runnable example, we'll use dummy certificate buffers.
  // In a real scenario, you'd load these from files as shown in the README.
  const certificatePublicKey = Buffer.from('-----BEGIN CERTIFICATE-----\n... (your cert content) ...\n-----END CERTIFICATE-----\n');
  const certificatePrivateKey = Buffer.from('-----BEGIN PRIVATE KEY-----\n... (your key content) ...\n-----END PRIVATE KEY-----\n');

  // Create an instance of the mock server
  const ldapServer = new LdapServerMock(
    ldapUsers,
    serverConfiguration,
    certificatePublicKey,
    certificatePrivateKey
  );

  try {
    console.log('Starting LDAP mock server...');
    await ldapServer.start();
    console.log(`LDAP mock server started on port ${serverConfiguration.port}`);

    // Simulate some work or keep the server running for tests
    // For a quick example, we'll stop it after a short delay
    await new Promise(resolve => setTimeout(resolve, 2000));

    console.log('Stopping LDAP mock server...');
    await ldapServer.stop();
    console.log('LDAP mock server stopped.');
  } catch (error) {
    console.error('Failed to run LDAP mock server:', error);
  }
}

main();