passport-ldapauth

passport-ldapauth is a Passport strategy that lets a Node.js application authenticate users against an LDAP directory or Microsoft Active Directory instead of a local user store. It plugs into any framework that supports Connect-style middleware (Express being the common case) the same way any other Passport strategy does: register it with passport.use(new LdapStrategy(options, verify)), then call passport.authenticate('ldapauth', ...) on the routes that need it.

Under the hood it is a thin, focused wrapper around ldapauth-fork, which does the actual LDAP bind/search/authenticate work. The library’s own responsibility is translating that into Passport’s success/fail/error contract: it pulls credentials from the request body, query string, or a custom credentialsLookup function (useful for wiring up HTTP Basic Auth via the basic-auth package), performs the LDAP authentication, and maps LDAP-specific failures (invalid credentials, bad search base, account locked) into Passport failure messages rather than hard errors.

A notable design detail is that LDAP connection options can be supplied either as a static object or as a callback function that is invoked fresh on every authenticate call — useful for applications that need to pull LDAP configuration from a database or config service rather than baking it into process startup. The library also has specific handling for the numeric error codes Active Directory returns for conditions like expired passwords, disabled accounts, and login-hour restrictions, translating each into its own customizable flash message.

What You Get

• A drop-in Passport strategy named ldapauth, used exactly like any other Passport strategy via passport.use() and passport.authenticate()
• Full pass-through of ldapauth-fork’s connection options (URL, bind DN, search base/filter, TLS options) for connecting to LDAP or LDAPS servers
• A pluggable credentialsLookup hook so credentials can come from HTTP Basic Auth or any other source instead of the default body/query lookup
• Dynamic, per-request configuration support by supplying an async options-resolving function instead of a static options object
• Granular, overridable flash messages for both generic LDAP failures and Active Directory-specific error codes (password expired, account locked, disabled, invalid logon hours, etc.)
• Bundled TypeScript type definitions for the strategy’s options and callbacks

Common Use Cases

• Adding “log in with your corporate directory credentials” to an internal Node.js admin panel or dashboard
• Migrating a legacy intranet app’s login form to Express/Passport while keeping the existing Active Directory as the source of truth for accounts
• Building a single sign-on gateway that authenticates against on-prem LDAP before issuing its own session or JWT
• Exposing a Basic Auth-protected API where credentials are validated against LDAP via a custom credentialsLookup
• Enforcing account-state policies (locked, expired, disabled) surfaced directly from Active Directory error codes in the login UI

Under The Hood

Architecture The entire strategy lives in a single file, lib/passport-ldapauth/strategy.js, exported through a thin index.js. The Strategy constructor extends passport-strategy’s base Strategy via the classic util.inherits pattern rather than ES6 classes, and stores either a static options object or an options-resolving callback function. The core logic sits in a private handleAuthentication function: it resolves credentials (from a custom credentialsLookup, or by looking up configurable field names in the request body/query), instantiates a fresh LdapAuth connection per authentication attempt, and translates ldapauth-fork’s callback result into Passport’s success/fail/error contract, with a dedicated error-code table mapping Active Directory failure codes to flash messages. The design is intentionally shallow — one strategy object, one delegation point to ldapauth-fork — so there is little internal structure to break.

Tech Stack Written in plain CommonJS JavaScript (no transpilation step) targeting Node.js >=10.13.0, with a single runtime dependency on ldapauth-fork (the actual LDAP client) and passport-strategy for the base class. Hand-maintained TypeScript declarations ship alongside the JS implementation in strategy.d.ts. The dev toolchain uses Mocha and Chai for tests, ESLint (eslint:recommended plus stricter custom rules including mandatory JSDoc) for linting, and Travis CI for continuous integration; there is no bundler or build step since the package ships its source directly.

Code Quality The test suite (test/strategy-test.js, over 400 lines) spins up a real embedded LDAP server and an Express app via supertest to exercise the strategy end-to-end across many authentication and error scenarios, rather than relying on mocks alone. ESLint’s require-jsdoc/valid-jsdoc rules are enforced, giving the codebase extensive inline documentation. Error handling is deliberately explicit: LDAP-specific failures are distinguished from genuine runtime errors, and an opt-in handleErrorsAsFailures mode lets applications choose the failure-vs-error boundary. The one dated aspect is the toolchain itself — Travis CI and callback-style (non-Promise) APIs throughout, reflecting the package’s age.

API Design The public surface mirrors Passport’s own conventions closely (same Strategy/verify(user, done) shape as passport-local), so anyone familiar with Passport strategies has near-zero onboarding cost. Configuration is thorough without being over-engineered: field name overrides, a custom credentials-lookup hook for adapting to non-form auth schemes, and support for supplying options as an async function for dynamic per-request configuration. Its most distinctive ergonomic touch is the built-in mapping of Active Directory’s numeric sub-error codes to individually overridable flash messages, sparing integrators from having to parse those codes themselves.