ldap-authentication 3.3.6 → 4.0.4

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

@@ -16,7 +16,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: [16.x, 17.x, 18.x, 20.x, 22.x]
+        node-version: [20.x, 22.x, 24.x]
 
     name: 'Integration Node v${{ matrix.node-version }}'
 
@@ -46,7 +46,7 @@ jobs:
         uses: actions/setup-node@v3
         with:
           node-version: ${{ matrix.node-version }}
-      - run: npm install
+      - run: npm ci
       - run: npm run test
 
       - name: Stop containers

package/.github/workflows/npm-publish.yml

@@ -1,33 +1,22 @@
-# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
-# For more information see: https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages
-
-name: Publish to NPM
+name: Publish Package
 
 on:
   release:
     types: [created]
 
+permissions:
+  id-token: write # Required for OIDC
+  contents: read
+
 jobs:
-  build:
+  publish:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-      - run: npm ci
 
-
-  publish-npm:
-    needs: build
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
-          registry-url: https://registry.npmjs.org/
+          node-version: '24'
+          registry-url: 'https://registry.npmjs.org'
       - run: npm ci
       - run: npm publish
-        env:
-          NODE_AUTH_TOKEN: ${{secrets.npm_token}}

package/README.md

@@ -221,6 +221,28 @@ auth()
 
 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.
+
+
+### AuthenticationResult Object
+
+AuthenticationResult object has the following fields:
+
+- `code`: number. constants:
+  - `AUTH_RESULT_FAILURE` = 0
+  - `AUTH_RESULT_SUCCESS` = 1
+  - `AUTH_RESULT_FAILURE_IDENTITY_NOT_FOUND` = -1
+  - `AUTH_RESULT_FAILURE_IDENTITY_AMBIGUOUS` = -2
+  - `AUTH_RESULT_FAILURE_CREDENTIAL_INVALID` = -3
+  - `AUTH_RESULT_FAILURE_UNCATEGORIZED` = -4
+- `identity`: identity supplied as string
+- `user`: user object if authentication is successful, otherwise null
+- `message`: authentication message array, which contains server messages
+- `client`: ldapClient instance
+
+
+## Old Stuff
+
 In version 2, The user object has a `raw` field that has the raw data from the LDAP/AD server. It can be used to access buffer objects (profile pics for example).
 
 Buffer data can now be accessed by `user.raw.profilePhoto`, etc, instead of `user.profilePhoto`.
@@ -260,4 +282,6 @@ export async function verifyLogin(email: string, password: string) {
 
 Version 2 supports Node version 12, 14, 15, 16, 17 and 18.
 
-Version 3 supports Node version 16, 17, 18, 20 and 22,
+Version 3 supports Node version 16, 17, 18, 20 and 22.
+
+Version 4 supports Node version 20 and above.

package/index.d.ts

@@ -20,7 +20,24 @@ declare module 'ldap-authentication' {
     explicitBufferAttributes?: string[]
   }
 
+  export const AUTH_RESULT_FAILURE = 0
+  export const AUTH_RESULT_SUCCESS = 1
+  export const AUTH_RESULT_FAILURE_IDENTITY_NOT_FOUND = -1
+  export const AUTH_RESULT_FAILURE_IDENTITY_AMBIGUOUS = -2
+  export const AUTH_RESULT_FAILURE_CREDENTIAL_INVALID = -3
+  export const AUTH_RESULT_FAILURE_UNCATEGORIZED = -4
+
+  export class AuthenticationResult {
+    constructor(authCode: number, identity: string, user: any, messages: string[], client: any)
+    readonly code: number
+    readonly identity: string
+    readonly user: any
+    readonly messages: string[]
+    readonly client: any
+  }
+
   export function authenticate(options: AuthenticationOptions): Promise<any>
+  export function authenticateResult(options: AuthenticationOptions): Promise<AuthenticationResult>
 
   export class LdapAuthenticationError extends Error {
     constructor(message: any)

package/index.js

@@ -38,12 +38,64 @@ function _ldapEscapeDN(s) {
   return ret
 }
 
+const AUTH_RESULT_FAILURE = 0
+const AUTH_RESULT_SUCCESS = 1
+const AUTH_RESULT_FAILURE_IDENTITY_NOT_FOUND = -1
+const AUTH_RESULT_FAILURE_IDENTITY_AMBIGUOUS = -2
+const AUTH_RESULT_FAILURE_CREDENTIAL_INVALID = -3
+const AUTH_RESULT_FAILURE_UNCATEGORIZED = -4
+
+class AuthenticationResult {
+  #authCode = AUTH_RESULT_FAILURE_UNCATEGORIZED
+  #identity
+  #user
+  #messages = []
+  #client
+
+  constructor(authCode, identity, user, messages, client) {
+    this.#authCode = authCode // one of the above constants
+    this.#identity = identity // identity supplied as string
+    this.#user     = user // user object found on ldap server OR null
+    this.#messages = messages // authentication messages array, which contains server messages
+    this.#client   = client // ldapClient instance
+  }
+
+  get code() {
+    return this.#authCode
+  }
+
+  get identity() {
+    return this.#identity
+  }
+
+  get messages() {
+    return this.#messages
+  }
+
+  get client() {
+    return this.#client
+  }
+
+  get user() {
+    return this.#user
+  }
+}
+
+const authenticationMessages = {
+  AUTH_RESULT_FAILURE: 'Authentication failed',
+  AUTH_RESULT_SUCCESS: 'Authentication successful',
+  AUTH_RESULT_FAILURE_IDENTITY_NOT_FOUND: 'Authentication identity not found',
+  AUTH_RESULT_FAILURE_IDENTITY_AMBIGUOUS: 'Authentication identity ambiguous',
+  AUTH_RESULT_FAILURE_CREDENTIAL_INVALID: 'Invalid credentials',
+  AUTH_RESULT_FAILURE_UNCATEGORIZED: 'Uncategorized authentication failure',
+}
+
 // bind and return the ldap client
 async function _ldapBind(dn, password, starttls, ldapOpts) {
   // TODO: check if ldapts expects escaped dn or not (possible double escaping problems?)
   dn = _ldapEscapeDN(dn)
   ldapOpts.connectTimeout = ldapOpts.connectTimeout || 5000
-  
+
   // When using StartTLS, we need to exclude tlsOptions from the Client constructor
   // and only pass them to the startTLS() method to avoid connection conflicts.
   // According to ldapts documentation:
@@ -52,7 +104,7 @@ async function _ldapBind(dn, password, starttls, ldapOpts) {
   // - For plain LDAP (ldap://): do NOT pass tlsOptions to Client constructor
   let clientOpts = ldapOpts
   const isLdaps = ldapOpts.url && ldapOpts.url.startsWith('ldaps://')
-  
+
   // Only pass tlsOptions to Client constructor if using ldaps:// protocol
   // For ldap:// protocol (plain or StartTLS), exclude tlsOptions from constructor
   if (!isLdaps && ldapOpts.tlsOptions) {
@@ -60,7 +112,7 @@ async function _ldapBind(dn, password, starttls, ldapOpts) {
     const { tlsOptions, ...optsWithoutTls } = ldapOpts
     clientOpts = optsWithoutTls
   }
-  
+
   let client = new ldapts.Client(clientOpts)
 
   if (starttls) {
@@ -115,8 +167,24 @@ async function _searchUser(
     !searchEntries[0] ||
     !searchEntries[0].dn
   ) {
-    user = null
+    return new AuthenticationResult(
+      AUTH_RESULT_FAILURE_IDENTITY_NOT_FOUND,
+      username,
+      null,
+      [authenticationMessages.AUTH_RESULT_FAILURE_IDENTITY_NOT_FOUND],
+      ldapClient
+    )
   } else {
+    if (searchEntries.length > 1) {
+      return new AuthenticationResult(
+        AUTH_RESULT_FAILURE_IDENTITY_AMBIGUOUS,
+        username,
+        null,
+        [authenticationMessages.AUTH_RESULT_FAILURE_IDENTITY_AMBIGUOUS],
+        ldapClient
+      )
+    }
+
     user = searchEntries[0]
   }
 
@@ -136,7 +204,14 @@ async function _searchUser(
       }
     }
   }
-  return user
+
+  return new AuthenticationResult(
+    AUTH_RESULT_SUCCESS,
+    username,
+    user,
+    [authenticationMessages.AUTH_RESULT_SUCCESS],
+    ldapClient
+  )
 }
 
 // search a groups which user is member
@@ -215,9 +290,17 @@ async function authenticateWithAdmin(
     if (ldapAdminClient && ldapAdminClient.isConnected) {
       await ldapAdminClient.unbind()
     }
-    throw new LdapAuthenticationError(error)
+
+    return new AuthenticationResult(
+      AUTH_RESULT_FAILURE,
+      username,
+      null,
+      [authenticationMessages.AUTH_RESULT_FAILURE, error.message || 'admin bind failed'],
+      ldapAdminClient
+    )
   }
-  let user = await _searchUser(
+
+  let searchResult = await _searchUser(
     ldapAdminClient,
     userSearchBase,
     usernameAttribute,
@@ -225,14 +308,21 @@ async function authenticateWithAdmin(
     attributes,
     explicitBufferAttributes
   )
+
+  let user = searchResult.user
+
   if (!user || !user.dn) {
     ldapOpts.log &&
       ldapOpts.log.trace(
         `admin did not find user! (${usernameAttribute}=${username})`
       )
     await ldapAdminClient.unbind()
-    throw new LdapAuthenticationError(
-      'user not found or usernameAttribute is wrong'
+    return new AuthenticationResult(
+      AUTH_RESULT_FAILURE_IDENTITY_NOT_FOUND,
+      username,
+      null,
+      [authenticationMessages.AUTH_RESULT_FAILURE_IDENTITY_NOT_FOUND],
+      ldapAdminClient
     )
   }
   let userDn = user.dn
@@ -243,7 +333,14 @@ async function authenticateWithAdmin(
     if (ldapUserClient && ldapUserClient.isConnected) {
       await ldapUserClient.unbind()
     }
-    throw new LdapAuthenticationError(error)
+
+    return new AuthenticationResult(
+      AUTH_RESULT_FAILURE_CREDENTIAL_INVALID,
+      username,
+      null,
+      [authenticationMessages.AUTH_RESULT_FAILURE_CREDENTIAL_INVALID, error.message || 'invalid credentials'],
+      ldapAdminClient
+    )
   }
   if (groupsSearchBase && groupClass && groupMemberAttribute) {
     let groups = await _searchUserGroups(
@@ -258,7 +355,14 @@ async function authenticateWithAdmin(
   }
   await ldapAdminClient.unbind()
   await ldapUserClient.unbind()
-  return user
+
+  return new AuthenticationResult(
+    AUTH_RESULT_SUCCESS,
+    username,
+    user,
+    [authenticationMessages.AUTH_RESULT_SUCCESS],
+    ldapAdminClient
+  )
 }
 
 async function authenticateWithUser(
@@ -283,14 +387,28 @@ async function authenticateWithUser(
     if (ldapUserClient && ldapUserClient.isConnected) {
       await ldapUserClient.unbind()
     }
-    throw new LdapAuthenticationError(error)
+
+    return new AuthenticationResult(
+      AUTH_RESULT_FAILURE,
+      username,
+      null,
+      [authenticationMessages.AUTH_RESULT_FAILURE, error.message || 'user bind failed'],
+      ldapUserClient
+    )
   }
   if (!usernameAttribute || !userSearchBase) {
     // if usernameAttribute is not provided, no user detail is needed.
     await ldapUserClient.unbind()
-    return true
+    return new AuthenticationResult(
+      AUTH_RESULT_SUCCESS,
+      username,
+      {},
+      [authenticationMessages.AUTH_RESULT_SUCCESS],
+      ldapUserClient
+    )
   }
-  let user = await _searchUser(
+
+  let searchResult = await _searchUser(
     ldapUserClient,
     userSearchBase,
     usernameAttribute,
@@ -298,14 +416,25 @@ async function authenticateWithUser(
     attributes,
     explicitBufferAttributes
   )
+
+  let user = searchResult.user
+
   if (!user || !user.dn) {
     ldapOpts.log &&
       ldapOpts.log.trace(
         `user logged in, but user details could not be found. (${usernameAttribute}=${username}). Probabaly wrong attribute or searchBase?`
       )
     await ldapUserClient.unbind()
-    throw new LdapAuthenticationError(
-      'user logged in, but user details could not be found. Probabaly usernameAttribute or userSearchBase is wrong?'
+
+    return new AuthenticationResult(
+      AUTH_RESULT_FAILURE,
+      username,
+      null,
+      [
+        authenticationMessages.AUTH_RESULT_FAILURE,
+        'user logged in, but user details could not be found. Probabaly usernameAttribute or userSearchBase is wrong?',
+      ],
+      ldapUserClient
     )
   }
   if (groupsSearchBase && groupClass && groupMemberAttribute) {
@@ -320,7 +449,14 @@ async function authenticateWithUser(
     user.groups = groups
   }
   await ldapUserClient.unbind()
-  return user
+
+  return new AuthenticationResult(
+    AUTH_RESULT_SUCCESS,
+    username,
+    user,
+    [authenticationMessages.AUTH_RESULT_SUCCESS],
+    ldapUserClient
+  )
 }
 
 async function verifyUserExists(
@@ -350,9 +486,16 @@ async function verifyUserExists(
     if (ldapAdminClient && ldapAdminClient.isConnected) {
       await ldapAdminClient.unbind()
     }
-    throw new LdapAuthenticationError(error)
+    return new AuthenticationResult(
+      AUTH_RESULT_FAILURE,
+      username,
+      null,
+      [authenticationMessages.AUTH_RESULT_FAILURE, error.message || 'admin bind failed'],
+      ldapAdminClient
+    )
   }
-  let user = await _searchUser(
+
+  let searchResult = await _searchUser(
     ldapAdminClient,
     userSearchBase,
     usernameAttribute,
@@ -360,14 +503,24 @@ async function verifyUserExists(
     attributes,
     explicitBufferAttributes
   )
+
+  let user = searchResult.user
+
   if (!user || !user.dn) {
     ldapOpts.log &&
       ldapOpts.log.trace(
         `admin did not find user! (${usernameAttribute}=${username})`
       )
     await ldapAdminClient.unbind()
-    throw new LdapAuthenticationError(
-      'user not found or usernameAttribute is wrong'
+    return new AuthenticationResult(
+      AUTH_RESULT_FAILURE_IDENTITY_NOT_FOUND,
+      username,
+      null,
+      [
+        authenticationMessages.AUTH_RESULT_FAILURE_IDENTITY_NOT_FOUND,
+        'user not found or usernameAttribute is wrong'
+      ],
+      ldapAdminClient
     )
   }
   if (groupsSearchBase && groupClass && groupMemberAttribute) {
@@ -382,10 +535,28 @@ async function verifyUserExists(
     user.groups = groups
   }
   await ldapAdminClient.unbind()
-  return user
+  return new AuthenticationResult(
+    AUTH_RESULT_SUCCESS,
+    username,
+    user,
+    [authenticationMessages.AUTH_RESULT_SUCCESS],
+    ldapAdminClient
+  )
 }
 
 async function authenticate(options) {
+  const result = await authenticateResult(options)
+
+  if (result.code !== AUTH_RESULT_SUCCESS) {
+    throw new LdapAuthenticationError(
+      result.messages[result.messages.length - 1]
+    )
+  }
+
+  return result.user
+}
+
+async function authenticateResult(options) {
   if (!options.userDn) {
     assert(options.adminDn, 'Admin mode adminDn must be provided')
     assert(options.adminPassword, 'Admin mode adminPassword must be provided')
@@ -402,6 +573,7 @@ async function authenticate(options) {
     options.ldapOpts && options.ldapOpts.url,
     'ldapOpts.url must be provided'
   )
+
   if (options.verifyUserExists) {
     assert(options.adminDn, 'Admin mode adminDn must be provided')
     assert(
@@ -424,6 +596,7 @@ async function authenticate(options) {
       options.explicitBufferAttributes
     )
   }
+
   assert(options.userPassword, 'userPassword must be provided')
   if (options.adminDn) {
     assert(
@@ -447,6 +620,7 @@ async function authenticate(options) {
       options.explicitBufferAttributes
     )
   }
+
   assert(options.userDn, 'adminDn/adminPassword OR userDn must be provided')
   return await authenticateWithUser(
     options.userDn,
@@ -477,7 +651,21 @@ class LdapAuthenticationError extends Error {
   }
 }
 
+module.exports.AUTH_RESULT_FAILURE = AUTH_RESULT_FAILURE
+module.exports.AUTH_RESULT_SUCCESS = AUTH_RESULT_SUCCESS
+module.exports.AUTH_RESULT_FAILURE_IDENTITY_NOT_FOUND =
+  AUTH_RESULT_FAILURE_IDENTITY_NOT_FOUND
+module.exports.AUTH_RESULT_FAILURE_IDENTITY_AMBIGUOUS =
+  AUTH_RESULT_FAILURE_IDENTITY_AMBIGUOUS
+module.exports.AUTH_RESULT_FAILURE_CREDENTIAL_INVALID =
+  AUTH_RESULT_FAILURE_CREDENTIAL_INVALID
+module.exports.AUTH_RESULT_FAILURE_UNCATEGORIZED =
+  AUTH_RESULT_FAILURE_UNCATEGORIZED
+
+module.exports.AuthenticationResult = AuthenticationResult
+
 module.exports.authenticate = authenticate
+module.exports.authenticateResult = authenticateResult
 module.exports.LdapAuthenticationError = LdapAuthenticationError
 
 module.exports.exportForTesting = {

package/package.json

@@ -1,15 +1,18 @@
 {
   "name": "ldap-authentication",
-  "version": "3.3.6",
+  "version": "4.0.4",
   "description": "A simple async nodejs library for LDAP user authentication",
   "main": "index.js",
   "types": "./index.d.ts",
+  "engines": {
+    "node": ">=20.0.0"
+  },
   "scripts": {
     "test": "node test/jasmine.js"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/shaozi/ldap-authentication.git"
+    "url": "git+https://github.com/shaozi/ldap-authentication.git"
   },
   "keywords": [
     "ldap",
@@ -36,9 +39,9 @@
   },
   "homepage": "https://github.com/shaozi/ldap-authentication#readme",
   "dependencies": {
-    "ldapts": "^7.3.1"
+    "ldapts": "^8.1.3"
   },
   "devDependencies": {
-    "jasmine": "^5.6.0"
+    "jasmine": "^6.0.0"
   }
 }

package/test/authentication-result.spec.js

@@ -0,0 +1,425 @@
+const {
+  authenticateResult,
+  AuthenticationResult,
+  AUTH_RESULT_SUCCESS,
+  AUTH_RESULT_FAILURE,
+  AUTH_RESULT_FAILURE_IDENTITY_NOT_FOUND,
+  AUTH_RESULT_FAILURE_IDENTITY_AMBIGUOUS,
+  AUTH_RESULT_FAILURE_CREDENTIAL_INVALID,
+  AUTH_RESULT_FAILURE_UNCATEGORIZED
+} = require('../index.js')
+
+const url = process.env.INGITHUB ? 'ldap://localhost:1389' : 'ldap://ldap:1389'
+
+describe('ldap-authentication test return AuthenticationResult', () => {
+  it('Use an admin user to check if user exists', async () => {
+    let options = {
+      ldapOpts: {
+        url: url,
+      },
+      adminDn: 'cn=read-only-admin,dc=example,dc=com',
+      adminPassword: 'password',
+      verifyUserExists: true,
+      userSearchBase: 'dc=example,dc=com',
+      usernameAttribute: 'uid',
+      username: 'gauss',
+    }
+
+    let result = await authenticateResult(options)
+    expect(result).toBeInstanceOf(AuthenticationResult)
+    expect(result.code).toEqual(AUTH_RESULT_SUCCESS)
+    expect(result.user).toBeTruthy()
+    expect(result.user.uid).toEqual('gauss')
+  })
+  it('Use an admin user to check if user exists and return attributes', async () => {
+    let options = {
+      ldapOpts: {
+        url: url,
+      },
+      adminDn: 'cn=read-only-admin,dc=example,dc=com',
+      adminPassword: 'password',
+      verifyUserExists: true,
+      userSearchBase: 'dc=example,dc=com',
+      usernameAttribute: 'uid',
+      username: 'gauss',
+      attributes: ['uid', 'sn'],
+    }
+
+    let result = await authenticateResult(options)
+    expect(result).toBeInstanceOf(AuthenticationResult)
+    expect(result.code).toEqual(AUTH_RESULT_SUCCESS)
+    expect(result.user).toBeTruthy()
+    expect(result.user.uid).toEqual('gauss')
+    expect(result.user.sn).toEqual('Bar1')
+    expect(result.user.cn).toBeUndefined()
+  })
+  it('Use an admin user to authenticate a regular user', async () => {
+    let options = {
+      ldapOpts: {
+        url: url,
+      },
+      adminDn: 'cn=read-only-admin,dc=example,dc=com',
+      adminPassword: 'password',
+      userPassword: 'password',
+      userSearchBase: 'dc=example,dc=com',
+      usernameAttribute: 'uid',
+      username: 'gauss',
+    }
+
+    let result = await authenticateResult(options)
+    expect(result).toBeInstanceOf(AuthenticationResult)
+    expect(result.code).toEqual(AUTH_RESULT_SUCCESS)
+    expect(result.user).toBeTruthy()
+    expect(result.user.uid).toEqual('gauss')
+  })
+  it('Use an admin user to authenticate a regular user and return attributes', async () => {
+    let options = {
+      ldapOpts: {
+        url: url,
+      },
+      adminDn: 'cn=read-only-admin,dc=example,dc=com',
+      adminPassword: 'password',
+      userPassword: 'password',
+      userSearchBase: 'dc=example,dc=com',
+      usernameAttribute: 'uid',
+      username: 'gauss',
+      attributes: ['uid', 'sn'],
+    }
+
+    let result = await authenticateResult(options)
+    expect(result).toBeInstanceOf(AuthenticationResult)
+    expect(result.code).toEqual(AUTH_RESULT_SUCCESS)
+    expect(result.user).toBeTruthy()
+    expect(result.user.uid).toEqual('gauss')
+    expect(result.user.sn).toEqual('Bar1')
+    expect(result.user.cn).toBeUndefined()
+  })
+  it('Use an regular user to authenticate iteself', async () => {
+    let options = {
+      ldapOpts: {
+        url: url,
+      },
+      userDn: 'cn=einstein,ou=users,dc=example,dc=com',
+      userPassword: 'password',
+      userSearchBase: 'dc=example,dc=com',
+      usernameAttribute: 'uid',
+      username: 'einstein',
+    }
+
+    let result = await authenticateResult(options)
+    expect(result).toBeInstanceOf(AuthenticationResult)
+    expect(result.code).toEqual(AUTH_RESULT_SUCCESS)
+    expect(result.user).toBeTruthy()
+    expect(result.user.uid).toEqual('einstein')
+  })
+  it('Use an regular user to authenticate iteself and return attributes', async () => {
+    let options = {
+      ldapOpts: {
+        url: url,
+      },
+      userDn: 'cn=einstein,ou=users,dc=example,dc=com',
+      userPassword: 'password',
+      userSearchBase: 'dc=example,dc=com',
+      usernameAttribute: 'uid',
+      username: 'einstein',
+      attributes: ['uid', 'sn'],
+    }
+
+    let result = await authenticateResult(options)
+    expect(result).toBeInstanceOf(AuthenticationResult)
+    expect(result.code).toEqual(AUTH_RESULT_SUCCESS)
+    expect(result.user).toBeTruthy()
+    expect(result.user.uid).toEqual('einstein')
+    expect(result.user.sn).toEqual('Bar2')
+    expect(result.user.cn).toBeUndefined()
+  })
+  it('Use an regular user to authenticate iteself without search', async () => {
+    let options = {
+      ldapOpts: {
+        url: url,
+      },
+      userDn: 'cn=einstein,ou=users,dc=example,dc=com',
+      userPassword: 'password',
+    }
+
+    let result = await authenticateResult(options)
+    expect(result.code).toEqual(AUTH_RESULT_SUCCESS)
+    expect(result.user).toBeTruthy()
+  })
+  it('Use an admin user to authenticate a regular user and fetch user group information', async () => {
+    let options = {
+      ldapOpts: {
+        url: url,
+      },
+      adminDn: 'cn=read-only-admin,dc=example,dc=com',
+      adminPassword: 'password',
+      userPassword: 'password',
+      userSearchBase: 'dc=example,dc=com',
+      usernameAttribute: 'uid',
+      username: 'gauss',
+      groupsSearchBase: 'dc=example,dc=com',
+      groupClass: 'groupOfNames',
+      groupMemberAttribute: 'member',
+      groupMemberUserAttribute: 'dn',
+    }
+
+    let result = await authenticateResult(options)
+    expect(result).toBeInstanceOf(AuthenticationResult)
+    expect(result.code).toEqual(AUTH_RESULT_SUCCESS)
+    expect(result.user).toBeTruthy()
+    expect(result.user.groups.length).toBeGreaterThan(0)
+    expect(result.user.groups[0].dn).toEqual('cn=科学A部,ou=groups,dc=example,dc=com')
+  })
+  it('Use regular user to authenticate and fetch user group information', async () => {
+    let options = {
+      ldapOpts: {
+        url: url,
+      },
+      userDn: 'cn=gauss,ou=users,dc=example,dc=com',
+      userPassword: 'password',
+      userSearchBase: 'dc=example,dc=com',
+      usernameAttribute: 'uid',
+      username: 'gauss',
+      groupsSearchBase: 'dc=example,dc=com',
+      groupClass: 'groupOfNames',
+      groupMemberAttribute: 'member',
+      groupMemberUserAttribute: 'dn',
+    }
+
+    let result = await authenticateResult(options)
+    expect(result).toBeInstanceOf(AuthenticationResult)
+    expect(result.code).toEqual(AUTH_RESULT_SUCCESS)
+    expect(result.user).toBeTruthy()
+    expect(result.user.groups.length).toBeGreaterThan(0)
+    expect(result.user.groups[0].dn).toEqual('cn=科学A部,ou=groups,dc=example,dc=com')
+    // backward compatible with 3.2
+    expect(result.user.groups[0].objectName).toEqual(
+      'cn=科学A部,ou=groups,dc=example,dc=com'
+    )
+  })
+  it('Not specifying groupMemberAttribute or groupMemberUserAttribute should not cause an error and fallback to default values', async () => {
+    let options = {
+      ldapOpts: {
+        url: url,
+      },
+      userDn: 'cn=gauss,ou=users,dc=example,dc=com',
+      userPassword: 'password',
+      userSearchBase: 'dc=example,dc=com',
+      usernameAttribute: 'uid',
+      username: 'gauss',
+      groupsSearchBase: 'dc=example,dc=com',
+      groupClass: 'groupOfUniqueNames',
+    }
+
+    let result = await authenticateResult(options)
+    expect(result).toBeInstanceOf(AuthenticationResult)
+    expect(result.code).toEqual(AUTH_RESULT_SUCCESS)
+    expect(result.user).toBeTruthy()
+    expect(result.user.groups.length).toBeLessThan(1)
+  })
+})
+
+describe('ldap-authentication negative test returns AuthenticationResult', () => {
+  it('wrong admin user should fail', async () => {
+    let options = {
+      ldapOpts: {
+        url: url,
+      },
+      adminDn: 'cn=not-exist,dc=example,dc=com',
+      adminPassword: 'password',
+      userPassword: 'password',
+      userSearchBase: 'dc=example,dc=com',
+      usernameAttribute: 'uid',
+      username: 'gauss',
+    }
+
+    let result = await authenticateResult(options)
+    expect(result).toBeInstanceOf(AuthenticationResult)
+    expect(result.code).toEqual(AUTH_RESULT_FAILURE)
+  })
+  it('wrong admin password should fail', async () => {
+    let options = {
+      ldapOpts: {
+        url: url,
+      },
+      adminDn: 'cn=read-only-admin,dc=example,dc=com',
+      adminPassword: 'wrongpassword',
+      userPassword: 'password',
+      userSearchBase: 'dc=example,dc=com',
+      usernameAttribute: 'uid',
+      username: 'gauss',
+    }
+
+    let result = await authenticateResult(options)
+    expect(result).toBeInstanceOf(AuthenticationResult)
+    expect(result.code).toEqual(AUTH_RESULT_FAILURE)
+  })
+  it('admin auth wrong username should fail', async () => {
+    let options = {
+      ldapOpts: {
+        url: url,
+      },
+      adminDn: 'cn=read-only-admin,dc=example,dc=com',
+      adminPassword: 'password',
+      userPassword: 'password',
+      userSearchBase: 'dc=example,dc=com',
+      usernameAttribute: 'uid',
+      username: 'wrong',
+    }
+
+    let result = await authenticateResult(options)
+    expect(result).toBeInstanceOf(AuthenticationResult)
+    expect(result.code).toEqual(AUTH_RESULT_FAILURE_IDENTITY_NOT_FOUND)
+  })
+  it('admin auth wrong user password should fail', async () => {
+    let options = {
+      ldapOpts: {
+        url: url,
+      },
+      adminDn: 'cn=read-only-admin,dc=example,dc=com',
+      adminPassword: 'password',
+      userPassword: 'wrongpassword',
+      userSearchBase: 'dc=example,dc=com',
+      usernameAttribute: 'uid',
+      username: 'gauss',
+    }
+
+    let result = await authenticateResult(options)
+    expect(result).toBeInstanceOf(AuthenticationResult)
+    expect(result.code).toEqual(AUTH_RESULT_FAILURE_CREDENTIAL_INVALID)
+  })
+  it('user auth wrong username should fail', async () => {
+    let options = {
+      ldapOpts: {
+        url: url,
+      },
+      userDn: 'cn=not-exist,dc=example,dc=com',
+      userPassword: 'password',
+      userSearchBase: 'dc=example,dc=com',
+      usernameAttribute: 'uid',
+      username: 'gauss',
+    }
+
+    let result = await authenticateResult(options)
+    expect(result).toBeInstanceOf(AuthenticationResult)
+    expect(result.code).toEqual(AUTH_RESULT_FAILURE)
+  })
+  it('user auth wrong user password should fail', async () => {
+    let options = {
+      ldapOpts: {
+        url: url,
+      },
+      userDn: 'cn=gauss,dc=example,dc=com',
+      userPassword: 'wrongpassword',
+      userSearchBase: 'dc=example,dc=com',
+      usernameAttribute: 'uid',
+      username: 'gauss',
+    }
+
+    let result = await authenticateResult(options)
+    expect(result).toBeInstanceOf(AuthenticationResult)
+    expect(result.code).toEqual(AUTH_RESULT_FAILURE)
+  })
+  it('Use an regular user to authenticate iteself without search with wrong password should fail', async () => {
+    let options = {
+      ldapOpts: {
+        url: url,
+      },
+      userDn: 'uid=einstein,dc=example,dc=com',
+      userPassword: 'wrongpassword',
+    }
+
+    let result = await authenticateResult(options)
+    expect(result).toBeInstanceOf(AuthenticationResult)
+    expect(result.code).toEqual(AUTH_RESULT_FAILURE)
+  })
+  it('Wrong attributes give failure', async () => {
+    let options = {
+      ldapOpts: {
+        url: url,
+      },
+      userDn: 'cn=einstein,ou=users,dc=example,dc=com',
+      userPassword: 'password',
+      usernameAttribute: 'wrongattribute',
+      userSearchBase: 'dc=example,dc=com',
+      username: 'einstein',
+    }
+
+    let result = await authenticateResult(options)
+    expect(result).toBeInstanceOf(AuthenticationResult)
+    expect(result.code).toEqual(AUTH_RESULT_FAILURE)
+  })
+  it('Unreachable ldap server should return failure', async () => {
+    let options = {
+      ldapOpts: {
+        url: 'ldap://x.forumsys.com',
+        connectTimeout: 2000,
+      },
+      userDn: 'uid=einstein,dc=example,dc=com',
+      userPassword: 'password',
+      usernameAttribute: 'cn',
+      userSearchBase: 'dc=example,dc=com',
+      username: 'einstein',
+    }
+
+    let result = await authenticateResult(options)
+    expect(result).toBeInstanceOf(AuthenticationResult)
+    expect(result.code).toEqual(AUTH_RESULT_FAILURE)
+  })
+  it('Unreachable ldap server should return failure (with starttls=true)', async () => {
+    let options = {
+      ldapOpts: {
+        url: 'ldap://x.forumsys.com',
+        connectTimeout: 2000,
+      },
+      userDn: 'uid=einstein,dc=example,dc=com',
+      userPassword: 'password',
+      usernameAttribute: 'cn',
+      userSearchBase: 'dc=example,dc=com',
+      username: 'einstein',
+      starttls: true,
+    }
+
+    let result = await authenticateResult(options)
+    expect(result).toBeInstanceOf(AuthenticationResult)
+    expect(result.code).toEqual(AUTH_RESULT_FAILURE)
+  })
+  it('Unmatched supplied groupMemberUserAttribute should return empty group list', async () => {
+    let options = {
+      ldapOpts: {
+        url: url,
+      },
+      userDn: 'cn=gauss,ou=users,dc=example,dc=com',
+      userPassword: 'password',
+      userSearchBase: 'dc=example,dc=com',
+      usernameAttribute: 'uid',
+      username: 'gauss',
+      groupsSearchBase: 'dc=example,dc=com',
+      groupClass: 'groupOfNames',
+      groupMemberAttribute: 'member',
+      groupMemberUserAttribute: 'dnWRONG',
+    }
+
+    let result = await authenticateResult(options)
+    expect(result).toBeInstanceOf(AuthenticationResult)
+    expect(result.user).toBeTruthy()
+    expect(result.user.groups.length).toBeLessThan(1)
+  })
+})
+
+describe('AuthenticationResult', () => {
+  it('AuthenticationResult creation and getters', async () => {
+    const result = new AuthenticationResult(
+      AUTH_RESULT_SUCCESS,
+      'testuser',
+      { cn: 'Test User' },
+      ['Authentication successful'],
+      {}
+    )
+
+    expect(result.code).toBe(AUTH_RESULT_SUCCESS)
+    expect(result.identity).toBe('testuser')
+    expect(result.user).toEqual({ cn: 'Test User' })
+    expect(result.messages).toEqual(['Authentication successful'])
+  })
+})