ldapauth-fork is a Node.js library for authenticating users against an LDAP server. It's a maintained fork of the original `node-ldapauth` package, primarily created to integrate newer versions of `ldapjs`, enable `tlsOptions` support, and address various community-reported issues. The package provides a robust API for user authentication, including support for group membership checks and configurable search filters. It ships with TypeScript type definitions since v4.0.0 and utilizes Bunyan for logging, aligning with `ldapjs`'s logging approach. The current stable version is 6.1.0, with a release cadence that addresses bug fixes, dependency updates, and new features, indicating active maintenance. Key differentiators include its explicit support for modern `ldapjs` versions, comprehensive configuration options for diverse LDAP setups, and improved error handling through `EventEmitter` inheritance.
npm install ldapauth-forkVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to instantiate `LdapAuth`, authenticate a user with a username and password, handle errors, and close the LDAP connection using modern async/await syntax. It utilizes environment variables for sensitive configuration options and shows basic error logging. A simple `console` logger is used, but a Bunyan instance is recommended for production.
Remove the `includeRaw` property from your `LdapAuthOptions` configuration. Data previously retrieved via `includeRaw` is no longer available directly through this option.
Review `ldapjs` v3.x changelog for any breaking changes that might indirectly affect your application's interaction with the LDAP server or how `ldapjs` options are interpreted. Test thoroughly after upgrade.
Applications should now listen for 'error' events on the `LdapAuth` instance using `auth.on('error', handler)` to properly catch and handle errors originating from the LDAP client or authentication process. Previous error handling mechanisms might no longer be sufficient.If you were relying on internal logging, you should now provide a Bunyan logger instance via the `log` option in `LdapAuthOptions`. Logs will be emitted at TRACE-level under component:ldapauth. Adjust your logging configuration accordingly.
Always ensure `searchBase` is correctly configured with a valid LDAP distinguished name (DN) where user accounts are located. Verify that the `searchFilter` correctly uses `{{username}}` to interpolate the provided username.Ensure `LdapAuth` is correctly imported as the default export using `const LdapAuth = require('ldapauth-fork');` for CommonJS or `import LdapAuth from 'ldapauth-fork';` for ESM, then instantiate it with `new LdapAuth(options);`.Verify the `url` in your `LdapAuthOptions` is correct and reachable. Check network connectivity between your application and the LDAP server. The `connectTimeout` option in `ldapjs` (which can be passed via `ldapauth-fork` options) can be adjusted if the server is slow to respond, though excessive timeouts may mask underlying issues.
Double-check the `bindDN` and `bindCredentials` in your `LdapAuthOptions`. Ensure the user specified by `bindDN` has sufficient read permissions on the `searchBase` to find user entries. If no `bindDN` is provided, ensure your LDAP server allows anonymous binds for searches.