Registry / auth-security / ldapauth-fork

ldapauth-fork

JSON →
library6.1.0jsnpmunverified

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-fork
INSTALL
IMPORT
SIG · LDAPAUTH-FORK
L
ldapauth-fork
auth-securityjavascriptv6.1.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

LdapAuth
import LdapAuth from 'ldapauth-fork'; // ESM import { LdapAuth } from 'ldapauth-fork'; // For explicit named import if package.json exports it as such or if a specific configuration requires it.
const LdapAuth = require('ldapauth-fork').default; // Incorrect if the main export is a default export, often LdapAuth is the default. import { LdapAuth } from 'ldapauth-fork/dist/LdapAuth';
Since v4.0.0, TypeScript types are provided. The library is typically used with a default export for the LdapAuth class. Ensure your Node.js version (>=16.14.0) and project configuration support ESM if using `import` syntax.
LdapAuthOptions
import type { LdapAuthOptions } from 'ldapauth-fork';
import { LdapAuthOptions } from 'ldapauth-fork'; // Using 'type' keyword for types is best practice.
This is a type import for configuring the LdapAuth constructor. It's available since v4.0.0 when TypeScript types were introduced.
CommonJS require
const LdapAuth = require('ldapauth-fork');
const { LdapAuth } = require('ldapauth-fork'); // Incorrect if LdapAuth is the default export. const auth = new require('ldapauth-fork')(options); // Less readable and not idiomatic.
This is the standard CommonJS pattern shown in the README. The primary `LdapAuth` class is exported as the module default.

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.

import LdapAuth, { LdapAuthOptions } from 'ldapauth-fork'; import type { User } from 'ldapjs'; const options: LdapAuthOptions = { url: process.env.LDAP_URL ?? 'ldaps://localhost:636', bindDN: process.env.LDAP_BIND_DN ?? 'cn=admin,dc=example,dc=org', bindCredentials: process.env.LDAP_BIND_CREDENTIALS ?? 'adminsecret', searchBase: process.env.LDAP_SEARCH_BASE ?? 'ou=users,dc=example,dc=org', searchFilter: process.env.LDAP_SEARCH_FILTER ?? '(uid={{username}})', log: console // Simple logger, use a Bunyan instance in production }; async function authenticateUser(username: string, password: string): Promise<User | null> { const auth = new LdapAuth(options); auth.on('error', (err) => { console.error(`LDAP Authentication Error: ${err.message}`); }); try { console.log(`Attempting to authenticate user: ${username}`); const user = await new Promise<User | null>((resolve, reject) => { auth.authenticate(username, password, (err, user) => { if (err) { console.error(`Authentication failed for ${username}: ${err.message}`); return reject(err); } if (user) { console.log(`User ${username} authenticated successfully.`); resolve(user as User); } else { console.log(`Authentication failed: No user found for ${username}.`); resolve(null); } }); }); return user; } catch (error) { console.error('An unexpected error occurred during authentication:', error); return null; } finally { await new Promise<void>((resolve, reject) => { auth.close((err) => { if (err) return reject(err); resolve(); }); }); console.log('LDAP connection closed.'); } } // Example usage: authenticateUser('testuser', 'testpassword') .then(user => { if (user) { console.log('Authenticated User Details:', user); } }) .catch(console.error);
Debug
Known issues
breakingThe `includeRaw` option has been removed from `LdapAuth` configuration. This is due to its removal from the underlying `ldapjs` library in its v3.x upgrade.
fix
Remove the `includeRaw` property from your `LdapAuthOptions` configuration. Data previously retrieved via `includeRaw` is no longer available directly through this option.
affects: >=6.0.0
breakingMajor version update of the underlying `ldapjs` library to v3.0.4. While `ldapauth-fork` attempts to abstract these changes, direct interaction with `ldapjs` options or behaviors might be affected.
fix
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.
affects: >=6.0.0
breakingThe `LdapAuth` class now inherits from `EventEmitter`. This changes how errors are propagated, specifically re-emitting `ldaps` errors.
fix
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.
affects: >=3.0.0
breakingThe tracing module was changed from an unspecified prior logger to [Bunyan](https://github.com/trentm/node-bunyan). The logger instance is now passed forward to `ldapjs`.
fix
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.
affects: >=4.0.0
gotchaThe `searchBase` option, while optional in some contexts, is critical for defining where user searches begin. Providing an empty string or an invalid `searchBase` can lead to authentication failures.
fix
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.
affects: All versions
Errors
Common errors & fixes
TypeError: auth.authenticate is not a function
Attempting to call `authenticate` on an uninitialized or incorrectly imported `LdapAuth` instance, often due to incorrect CommonJS `require` syntax.
fix
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);`.
Error: Connect Timeout (ldapauth-fork)
The LDAP server did not respond within the configured connection timeout period, indicating network issues, an incorrect LDAP URL, or a non-responsive server.
fix
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.
LdapAuth: Error: [LDAP_PROTOCOL_ERROR] 00000000: LdapErr: DSID-0C090C5D, comment: In order to perform this operation a successful bind must be completed on the connection.
This typically means the `bindDN` and `bindCredentials` provided for the admin user (if configured) are incorrect or lack the necessary permissions to perform the `searchBase` lookup.
fix
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.
Upgrade
Version history
6.1.0latest on npm
Audit
Dependencies
ldapjsrequiredCore LDAP client library for all communication with the LDAP server.
bunyanoptionalUsed for structured logging within the library and passed through to ldapjs.
Agent activity
9 hits · last 30 days
node
8
OpenAI (training)
1
Resources
ldapauth-fork — npm install ldapauth-fork · libregistry