ldapha

Lightweight LDAP helper for Active Directory password changes and simple searches
Built on top of ldapts · Promise-based · Minimal API

Features

• Change user passwords in Active Directory (self-service & admin reset)
• Simple LDAP search / list operations
• Automatic connection & clean unbind
• Works with both ldap:// and ldaps://
• TypeScript-friendly (ships with types)
• Very small surface area — ideal for password reset forms & user portals

Installation

npm install ldapha
# or
yarn add ldapha
# or
pnpm add ldapha

Usage

1. Import & Initialize

import ldapha from 'ldapha';
// or
const ldapha = require('ldapha').default;

const ldap = ldapha('ldaps://ldap.yourcompany.com:636', {
  // optional global settings
  timeout: 10000,
  connectTimeout: 7000,
  tlsOptions: {
    rejectUnauthorized: true,           // set to false only for self-signed/testing
    // ca: fs.readFileSync('path/to/ca.pem'),   // if needed
  }
});

2. Change Password (user self-service)

async function handlePasswordChange(userDn, oldPw, newPw) {
  try {
    await ldap.changePassword(userDn, oldPw, newPw);
    console.log('Password changed successfully');
  } catch (err) {
    console.error('Password change failed:', err.message);
    // Common errors: invalid credentials, policy violation, connection issues
  }
}

3. Admin Reset (bypass old password)

await ldap.changePassword(
  'CN=John Doe,OU=Users,DC=company,DC=com',
  '[email protected]',           // ← admin credentials here
  'NewSecurePass123!',
  { adminReset: true }
);

Important: For admin reset, bind with an account that has permission to reset passwords (usually Domain Admin or delegated rights).

4. Search / List entries

const entries = await ldap.list(
  'OU=Users,DC=company,DC=com',          // base DN
  '[email protected]',         // bind user
  'SecretServicePass456!',               // bind password
  {
    filter: '(&(objectClass=user)(mail=*@company.com))',
    scope: 'sub',
    attributes: ['cn', 'mail', 'sAMAccountName', 'memberOf']
  }
);

console.log(entries);
// → [ { dn: '...', cn: '...', mail: '...', ... }, ... ]

API

ldapha(url: string, options?: ClientOptions): {
  list(
    baseDn: string,
    bindDn: string,
    bindPw: string,
    opts?: {
      filter?: string;
      scope?: 'base' | 'one' | 'sub';
      attributes?: string[];
      [key: string]: any;
    }
  ): Promise<SearchEntry[]>;

  changePassword(
    userDn: string,
    oldPassword: string,
    newPassword: string,
    opts?: { adminReset?: boolean }
  ): Promise<void>;
}

Requirements & Notes

• Use LDAPS (ldaps://…:636) when changing passwords — Active Directory requires secure connection for unicodePwd modifications.
• Passwords must meet your domain policy (length, complexity, history).
• The library quotes passwords automatically (\"password\") and uses correct unicodePwd format.
• Tested primarily against Microsoft Active Directory — may work with other LDAP servers that support unicodePwd.

Security Considerations

• Never log passwords or store them in plain text.
• Use short-lived service accounts with minimal permissions.
• Prefer LDAPS + proper certificate validation in production.
• Consider connection pooling if you make many operations (not included in this tiny helper).

License

MIT

Related Projects

• ldapts – the excellent underlying LDAP client (TypeScript, modern, actively maintained)

Made with ❤️ for simple AD password reset flows
Questions / PRs welcome!