ldap-authentication 4.0.5 → 4.2.0

package/.github/workflows/integration-test.yml

@@ -16,7 +16,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: [20.x, 22.x, 24.x]
+        node-version: [22.x, 24.x]
 
     name: 'Integration Node v${{ matrix.node-version }}'
 

package/README.md

@@ -25,7 +25,11 @@ This library use `ldapts` as the underneath library. It has three modes of authe
    then does a search on the user and return the user's details.
 
 3. **Verify user exists**. If an `verifyUserExists : true` is provided, the library will login (ldap bind) with the admin user,
-   then search for the user to be verified. If the user exists, user details will be returned (without verifying the user's password).
+    then search for the user to be verified. If the user exists, user details will be returned (without verifying the user's password).
+
+In addition, the `fetchUsers()` function can be used to fetch all users under a search base, using the admin
+account to search (without any username or password of the individual users). The search always uses
+LDAP paged results, so the common server-side limit of 1000 entries per search does not apply.
 
 ## Features
 
@@ -102,6 +106,22 @@ let authenticated = await authenticate({
 })
 ```
 
+#### Fetch all users (admin search, without user passwords)
+
+```javascript
+const { fetchUsers } = require('ldap-authentication')
+
+let users = await fetchUsers({
+  ldapOpts: { url: 'ldap://ldap.forumsys.com' },
+  adminDn: 'cn=read-only-admin,dc=example,dc=com',
+  adminPassword: 'password',
+  userSearchBase: 'dc=example,dc=com',
+  // userFilter: '(objectClass=person)',  // default: (|(uid=*)(sAMAccountName=*))
+  // attributes: ['uid', 'sn', 'mail'],   // omitted = all attributes
+  // pageSize: 500,                       // default: 1000
+})
+```
+
 #### Complete example
 
 The library works with both CommonJS and ES modules:
@@ -218,6 +238,12 @@ auth()
 - `username`: The username to authenticate with. It is used together with the name in `usernameAttribute`
   to construct an ldap filter as `({attribute}={username})`
   to find the user and get user details in LDAP. Example: `some user input`
+- `userFilter`: (used by `fetchUsers()`) The ldap search filter to select the users to return.
+  By default it is `(|(uid=*)(sAMAccountName=*))`, which matches both POSIX (`uid`)
+  and Active Directory (`sAMAccountName`) users. Example: `'(objectClass=person)'`,
+  or `'(objectClass=*)'` to match everything
+- `pageSize`: (used by `fetchUsers()`) The number of entries to fetch per page for the paged
+  search. Default: `1000`
 - `attributes`: A list of attributes of a user details to be returned from the LDAP server.
   If is set to `[]` or ommited, all details will be returned. Example: `['sn', 'cn']`
 - `starttls`: Boolean. Use `STARTTLS` or not. When `true`, the connection will be upgraded to TLS
@@ -234,6 +260,8 @@ The user object if `authenticate()` is success.
 
 In version 4, a new function is added: `authenticateResult()`. It has the same call signature as `authenticate()` but returns an object `AuthenticationResult` with more details.
 
+`fetchUsers()` returns an array of user objects, one per matched LDAP entry (each with its `dn` and the returned attributes), or an empty array if no user matches the filter.
+
 
 ### AuthenticationResult Object
 
@@ -295,4 +323,4 @@ Version 2 supports Node version 12, 14, 15, 16, 17 and 18.
 
 Version 3 supports Node version 16, 17, 18, 20 and 22.
 
-Version 4 supports Node version 20 and above.
+Version 4 supports Node version 22 and above.

package/index.d.ts

@@ -37,9 +37,37 @@ declare module 'ldap-authentication' {
     readonly client: any
   }
 
+  export interface FetchUsersOptions {
+    ldapOpts: ClientOptions
+    adminDn: string
+    adminPassword: string
+    userSearchBase: string
+    /**
+     * LDAP search filter used to select the users to return.
+     * Defaults to `(|(uid=*)(sAMAccountName=*))`, which matches both
+     * POSIX (`uid`) and Active Directory (`sAMAccountName`) users.
+     * Example: `'(objectClass=person)'`, or `'(objectClass=*)'` to match everything.
+     */
+    userFilter?: string
+    /** A list of attributes of the users to be returned from the LDAP server. If omitted, all details will be returned. */
+    attributes?: string[]
+    /** A list of attributes to be returned as base64-encoded strings. */
+    explicitBufferAttributes?: string[]
+    /** Number of entries to fetch per page for the paged search. Defaults to 1000. */
+    pageSize?: number
+    starttls?: boolean
+  }
+
   export function authenticate(options: AuthenticationOptions): Promise<any>
   export function authenticateResult(options: AuthenticationOptions): Promise<AuthenticationResult>
 
+  /**
+   * Bind with the admin account and search all users under `userSearchBase`.
+   * The search always uses paged results, so results are not limited by the
+   * common server-side limit of 1000 entries.
+   */
+  export function fetchUsers(options: FetchUsersOptions): Promise<any[]>
+
   export class LdapAuthenticationError extends Error {
     constructor(message: any)
     name: string

package/index.js

@@ -45,6 +45,9 @@ const AUTH_RESULT_FAILURE_IDENTITY_AMBIGUOUS = -2
 const AUTH_RESULT_FAILURE_CREDENTIAL_INVALID = -3
 const AUTH_RESULT_FAILURE_UNCATEGORIZED = -4
 
+const DEFAULT_FETCH_USERS_FILTER = '(|(uid=*)(sAMAccountName=*))'
+const DEFAULT_FETCH_USERS_PAGE_SIZE = 1000
+
 class AuthenticationResult {
   #authCode = AUTH_RESULT_FAILURE_UNCATEGORIZED
   #identity
@@ -273,6 +276,55 @@ async function _searchUserGroups(
   return groups
 }
 
+// search all users under the search base and return the list of user objects
+async function _fetchAllUsers(
+  ldapClient,
+  searchBase,
+  userFilter,
+  attributes = null,
+  explicitBufferAttributes = null,
+  pageSize = DEFAULT_FETCH_USERS_PAGE_SIZE
+) {
+  let filter = userFilter || DEFAULT_FETCH_USERS_FILTER
+
+  let searchOptions = {
+    filter: filter,
+    scope: 'sub',
+    // always use paged results, so more than the usual server-side limit
+    // (usually 1000 entries per page) can be returned
+    paged: { pageSize: pageSize },
+  }
+  if (attributes) {
+    searchOptions.attributes = attributes
+  }
+  if (explicitBufferAttributes) {
+    searchOptions.explicitBufferAttributes = explicitBufferAttributes
+  }
+
+  const { searchEntries } = await ldapClient.search(searchBase, searchOptions)
+
+  let users = searchEntries || []
+  // when attribute endwith ;binary, ldapts returns Buffer, we convert them into base64 string
+  for (let user of users) {
+    if (user != null && attributes != null) {
+      for (let attr of attributes) {
+        if (attr.endsWith(';binary') && Buffer.isBuffer(user[attr])) {
+          user[attr] = user[attr].toString('base64')
+        }
+      }
+    }
+    // when attribute is one of the explicitBufferAttributes, should convert to base64 string
+    if (user != null && explicitBufferAttributes != null) {
+      for (let attr of explicitBufferAttributes) {
+        if (Buffer.isBuffer(user[attr])) {
+          user[attr] = user[attr].toString('base64')
+        }
+      }
+    }
+  }
+  return users
+}
+
 async function authenticateWithAdmin(
   adminDn,
   adminPassword,
@@ -561,6 +613,51 @@ async function verifyUserExists(
   )
 }
 
+// fetch all users under the search base, using the admin account to search.
+// the search always uses paged results so the common server-side limit of
+// 1000 entries does not apply.
+async function fetchUsers(options) {
+  assert(
+    options.ldapOpts && options.ldapOpts.url,
+    'fetchUsers: ldapOpts.url must be provided'
+  )
+  assert(options.adminDn, 'fetchUsers: adminDn must be provided')
+  assert(options.adminPassword, 'fetchUsers: adminPassword must be provided')
+  assert(options.userSearchBase, 'fetchUsers: userSearchBase must be provided')
+
+  let ldapAdminClient
+  try {
+    ldapAdminClient = await _ldapBind(
+      options.adminDn,
+      options.adminPassword,
+      options.starttls,
+      options.ldapOpts
+    )
+  } catch (error) {
+    if (ldapAdminClient && ldapAdminClient.isConnected) {
+      await ldapAdminClient.unbind()
+    }
+    throw new LdapAuthenticationError(error.message || 'admin bind failed')
+  }
+
+  try {
+    return await _fetchAllUsers(
+      ldapAdminClient,
+      options.userSearchBase,
+      options.userFilter,
+      options.attributes,
+      options.explicitBufferAttributes,
+      options.pageSize || DEFAULT_FETCH_USERS_PAGE_SIZE
+    )
+  } catch (error) {
+    throw new LdapAuthenticationError(error.message || 'user search failed')
+  } finally {
+    if (ldapAdminClient && ldapAdminClient.isConnected) {
+      await ldapAdminClient.unbind()
+    }
+  }
+}
+
 async function authenticate(options) {
   const result = await authenticateResult(options)
 
@@ -686,6 +783,7 @@ module.exports.AuthenticationResult = AuthenticationResult
 
 module.exports.authenticate = authenticate
 module.exports.authenticateResult = authenticateResult
+module.exports.fetchUsers = fetchUsers
 module.exports.LdapAuthenticationError = LdapAuthenticationError
 
 module.exports.exportForTesting = {

package/index.mjs

@@ -11,6 +11,7 @@ export {
   LdapAuthenticationError,
   authenticate,
   authenticateResult,
+  fetchUsers,
 } from './index.js'
 
 export default ldapAuthentication

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ldap-authentication",
-  "version": "4.0.5",
+  "version": "4.2.0",
   "description": "A simple async nodejs library for LDAP user authentication",
   "main": "index.js",
   "types": "./index.d.ts",
@@ -14,7 +14,7 @@
     "./package.json": "./package.json"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.0.0"
   },
   "scripts": {
     "test": "node test/jasmine.js"

package/test/fetch-users.spec.js

@@ -0,0 +1,136 @@
+const { fetchUsers, LdapAuthenticationError } = require('../index.js')
+
+const url = process.env.INGITHUB ? 'ldap://localhost:1389' : 'ldap://ldap:1389'
+
+describe('ldap-authentication fetchUsers test', () => {
+  const baseOptions = {
+    ldapOpts: {
+      url: url,
+    },
+    adminDn: 'cn=read-only-admin,dc=example,dc=com',
+    adminPassword: 'password',
+    userSearchBase: 'dc=example,dc=com',
+  }
+
+  it('Should return all users with the default filter', async () => {
+    let users = await fetchUsers(baseOptions)
+
+    expect(Array.isArray(users)).toBe(true)
+    expect(users.length).toBe(2)
+    let uids = users.map((user) => user.uid)
+    expect(uids).toContain('gauss')
+    expect(uids).toContain('einstein')
+    for (let user of users) {
+      expect(user.dn).toBeTruthy()
+    }
+  })
+
+  it('Should return only the requested attributes', async () => {
+    let users = await fetchUsers({
+      ...baseOptions,
+      attributes: ['uid', 'sn'],
+    })
+
+    expect(users.length).toBe(2)
+    let gauss = users.find((user) => user.uid === 'gauss')
+    expect(gauss).toBeTruthy()
+    expect(gauss.sn).toEqual('Bar1')
+    expect(gauss.cn).toBeUndefined()
+  })
+
+  it('Should return only matching users with a custom userFilter', async () => {
+    let users = await fetchUsers({
+      ...baseOptions,
+      userFilter: '(uid=gauss)',
+    })
+
+    expect(users.length).toBe(1)
+    expect(users[0].uid).toEqual('gauss')
+    expect(users[0].sn).toEqual('Bar1')
+  })
+
+  it('Should return all entries including non-users when userFilter matches everything', async () => {
+    let users = await fetchUsers({
+      ...baseOptions,
+      userFilter: '(objectClass=*)',
+    })
+
+    expect(users.length).toBeGreaterThan(2)
+    let dns = users.map((user) => user.dn)
+    expect(dns).toContain('cn=gauss,ou=users,dc=example,dc=com')
+    expect(dns).toContain('cn=科学A部,ou=groups,dc=example,dc=com')
+  })
+
+  it('Should return empty list when userFilter matches nothing', async () => {
+    let users = await fetchUsers({
+      ...baseOptions,
+      userFilter: '(uid=does-not-exist)',
+    })
+
+    expect(users).toEqual([])
+  })
+})
+
+describe('ldap-authentication fetchUsers negative test', () => {
+  const baseOptions = {
+    ldapOpts: {
+      url: url,
+    },
+    adminDn: 'cn=read-only-admin,dc=example,dc=com',
+    adminPassword: 'password',
+    userSearchBase: 'dc=example,dc=com',
+  }
+
+  it('wrong admin password should throw LdapAuthenticationError', async () => {
+    let options = {
+      ...baseOptions,
+      adminPassword: 'wrongpassword',
+    }
+
+    let e = null
+    try {
+      await fetchUsers(options)
+    } catch (error) {
+      e = error
+    }
+
+    expect(e).toBeTruthy()
+    expect(e).toBeInstanceOf(LdapAuthenticationError)
+  })
+
+  it('wrong admin dn should throw LdapAuthenticationError', async () => {
+    let options = {
+      ...baseOptions,
+      adminDn: 'cn=not-exist,dc=example,dc=com',
+    }
+
+    let e = null
+    try {
+      await fetchUsers(options)
+    } catch (error) {
+      e = error
+    }
+
+    expect(e).toBeTruthy()
+    expect(e).toBeInstanceOf(LdapAuthenticationError)
+  })
+
+  it('missing userSearchBase should throw', async () => {
+    let options = {
+      ldapOpts: {
+        url: url,
+      },
+      adminDn: 'cn=read-only-admin,dc=example,dc=com',
+      adminPassword: 'password',
+    }
+
+    let e = null
+    try {
+      await fetchUsers(options)
+    } catch (error) {
+      e = error
+    }
+
+    expect(e).toBeTruthy()
+  })
+})