Migrate from ldapjs to ldapts

Migrate a Node.js LDAP application from ldapjs to ldapts by updating clients, binds, searches, errors, cleanup, TLS settings, and tests.

Type
Tutorial
Level
Intermediate
Technologies
Node.js, LDAP, LDAPS
On this page

Why Migrate from ldapjs to ldapts?

The ldapjs package is now officially deprecated and unmaintained as of May 2024. Its repository has been archived, and it will no longer receive updates or security patches. This creates mounting operational and security risks for any project relying on ldapjs. The maintainers themselves recommend migrating to more modern LDAP client libraries. The Node.js LDAP ecosystem now strongly favors ldapts as the recommended replacement, particularly for projects where security, maintainability, and forward-compatibility are priorities.

Continuing to use ldapjs exposes your infrastructure to unsupported legacy dependencies, risk of breakage with future Node.js versions, and unaddressed vulnerabilities. Migration is not optional for organizations concerned with operational integrity and compliance.

ldapts: The Modern Replacement for Node.js LDAP

ldapts is a modern, actively maintained LDAP client for Node.js, written natively in TypeScript. This brings several tangible improvements over ldapjs:

  • Full TypeScript Support: Type safety is native and enforced in all major operations, significantly reducing runtime errors and easing maintenance, especially for teams invested in TypeScript best practices.
  • Async/Await and Promise-Based Operations: ldapts embraces modern JavaScript idioms, replacing callback-based APIs with promises and async/await. This streamlines asynchronous flow and modernizes error management.
  • Improved TLS and StartTLS Handling: ldapts offers explicit, well-documented handling for TLS/SSL and StartTLS, closing historic gaps in the security model present in ldapjs.
  • Better Maintenance and Compatibility: ldapts maintains support for current Node.js versions and actively responds to issues, in stark contrast to the abandoned state of ldapjs.

However, ldapts is not a strict drop-in replacement. While much of the conceptual workflow remains familiar, and basic configurations are often similar, key breaking changes impact both API usage and underlying types.

Core API and Breaking Changes: What to Expect in Migration

In a standard migration, certain ldapjs operations may function almost unchanged—especially straightforward authentication or search flows using only documented configuration options. However, there are non-trivial breaking changes and areas requiring code review:

  • Client Instantiation: ldapts uses TypeScript imports and the LDAP client is constructed with a different object signature.
  • Configuration Objects: Parameters for connection, authentication, and especially StartTLS are not always a 1:1 match; you must review and align them with ldapts documentation.
  • Custom Resolver Signatures: Any custom code handling LDAP search, user extraction, or resolver logic will need updating to match new types and promise-based signatures. For example, callbacks must be replaced with async functions returning promises.
  • Error Handling: ldapts rejects errors using promises rather than through callback arguments. This changes both the placement and structure of error-handling code.
  • TLS/StartTLS Configuration: Options and config keys for enabling StartTLS or secure connections may differ. Explicitly review any security-related client options.

While default authentication and basic directory operations may see minimal disruption, anything that touches internal ldapjs types, expects callback-based error propagation, or provides custom search behavior will require a deliberate refactor.

Assessing Custom vs. Standard LDAP Integrations

If your application uses only standard authentication flows and relies on straightforward configuration (such as url, bind DN, and search filter), the migration to ldapts may be relatively seamless. For most simple configurations, existing code and settings can be adapted with minimal changes.

However, this does not hold true where:

  • Your project defines custom resolvers for user search, authentication, or group membership extraction. Here, resolver function signatures and returned types are likely incompatible and must be explicitly updated for ldapts.
  • You reference internal ldapjs types, or use custom operational flows that interact beyond the strict public surface of the ldapjs API. These integrations will require a focused review of all signature and return type changes.
  • TLS/StartTLS or custom SSL handling is in play. Migration here always mandates config review due to differing parameter names and supported features.

Projects with custom authentication layers, transformers, group mapping, or directory search abstractions should expect a more hands-on migration, involving both refactoring and revalidation of all affected pathways.

Testing and Validation After Migration

Post-migration, comprehensive testing is essential. Operational differences between ldapjs and ldapts—especially around error propagation, async behavior, and TLS setup—can introduce subtle runtime issues that surface only under real-world conditions.

After migration:

  • Validate All Authentication Flows: Test all user and service binds, ensuring correct handling of failed authentication, invalid credentials, and successful logins.
  • Exhaustively Check Search Operations: Confirm user and group searches return expected results, and edge cases (such as empty or non-existent queries) are handled.
  • Assess Custom Logic: Any custom resolvers, transformers, or directory search handlers should be unit- and integration-tested with a live LDAP server.
  • TLS and StartTLS Pathways: Explicitly verify all TLS-secured and StartTLS connections work as intended, paying attention to both certificate handling and fallback scenarios.
  • Review Error Handling: Confirm that all code paths correctly surface and manage errors as rejected promises, not as callback arguments or synchronous exceptions.

A migration is not complete until both automated and user-driven tests confirm operational parity and expected behavior across all authentication and directory integration touchpoints.

Open Gaps and Migration Risks: What to Watch Out For

  • No Official Migration Scripts: At the time of writing, there is no generalized, automated migration tool to convert ldapjs codebases to ldapts; migration is a hands-on developer task.
  • Documentation Remains Ecosystem-Specific: Most detailed migration advice, including authoritative type and resolver changes, is available in the context of specific projects or plugins. There is no canonical, officially maintained migration mapping table for all ldapjs-to-ldapts functions and types.
  • Unavoidable Manual Code Review: Custom and legacy code—especially involving non-standard LDAP operations or types—must be manually inspected and tested. Do not assume backward compatibility or safe operation without review.
  • Legacy Support Available, but Risky: While some older plugins and libraries still work with ldapjs, relying on them prolongs security and maintenance risks.

Authoritative Migration Resources

  • ldapjs decommissioning notice and repository (official project status and support rationale)
  • ldapts migration guide (detailed stepwise instructions for updating Backstage plugin code and general notes on configuration, resolver signatures, and StartTLS options)
  • Plugin and backend migration documentation for context-specific integration details and further authoritative implementation guidance

Sources

Related resources