ldap-authentication 3.3.3 → 3.3.6

package/.devcontainer/docker-compose.yml

@@ -8,7 +8,7 @@ services:
     command: sleep infinity
 
   ldap:
-    image: bitnami/openldap
+    image: symas/openldap:2.6
     ports:
       - '1389:1389'
       - '1636:1636'

package/README.md

@@ -147,6 +147,43 @@ async function auth() {
 auth()
 ```
 
+### Example with StartTLS
+
+```javascript
+import { authenticate } from 'ldap-authentication'
+
+async function auth() {
+  // auth with admin
+  let options = {
+    ldapOpts: {
+      url: 'ldap://ldap.example.com',
+      tlsOptions: {
+        rejectUnauthorized: false, // For self-signed certificates
+        minVersion: 'TLSv1.2',
+        servername: 'ldap.example.com' // For SNI (Server Name Indication)
+      }
+    },
+    starttls: true, // Enable StartTLS
+    adminDn: 'cn=admin,dc=example,dc=com',
+    adminPassword: 'password',
+    userPassword: 'password',
+    userSearchBase: 'dc=example,dc=com',
+    usernameAttribute: 'uid',
+    username: 'testuser'
+  }
+
+  let user = await authenticate(options)
+  console.log(user)
+}
+
+auth()
+```
+
+**Important Notes for StartTLS:**
+- Use `ldap://` URLs with `starttls: true` (not `ldaps://`)
+- For `ldaps://` URLs, omit `starttls` and the connection will use TLS from the start
+- TLS options like `rejectUnauthorized`, `minVersion`, and `servername` can be specified in `ldapOpts.tlsOptions`
+
 ## Parameters
 
 - `ldapOpts`: This is passed to `ldapts` client directly
@@ -172,7 +209,9 @@ auth()
   to find the user and get user details in LDAP. Example: `some user input`
 - `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
+- `starttls`: Boolean. Use `STARTTLS` or not. When `true`, the connection will be upgraded to TLS
+  using the STARTTLS extended operation. TLS options can be specified in `ldapOpts.tlsOptions`.
+  Note: Use `starttls: true` with `ldap://` URLs, not `ldaps://` URLs
 - `groupsSearchBase`: if specified with groupClass, will serve as search base for authenticated user groups
 - `groupClass`: if specified with groupsSearchBase, will be used as objectClass in search filter for authenticated user groups
 - `groupMemberAttribute`: if specified with groupClass and groupsSearchBase, will be used as member name (if not specified this defaults to `member`) in search filter for authenticated user groups

package/docker-compose.yml

@@ -1,6 +1,6 @@
 services:
   ldap:
-    image: bitnami/openldap:2.6.3
+    image: symas/openldap:2.6
     ports:
       - '1389:1389'
       - '1636:1636'

package/index.d.ts

@@ -17,6 +17,7 @@ declare module 'ldap-authentication' {
     groupMemberUserAttribute?: string
     userPassword?: string
     attributes?: string[]
+    explicitBufferAttributes?: string[]
   }
 
   export function authenticate(options: AuthenticationOptions): Promise<any>

package/index.js

@@ -43,7 +43,25 @@ 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
-  let client = new ldapts.Client(ldapOpts)
+  
+  // 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:
+  // - For LDAPS (ldaps://): pass tlsOptions to Client constructor
+  // - For StartTLS (ldap://): do NOT pass tlsOptions to Client constructor, only to startTLS()
+  // - 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) {
+    // Create a shallow copy of ldapOpts without tlsOptions for the Client constructor
+    const { tlsOptions, ...optsWithoutTls } = ldapOpts
+    clientOpts = optsWithoutTls
+  }
+  
+  let client = new ldapts.Client(clientOpts)
 
   if (starttls) {
     await client.startTLS(ldapOpts.tlsOptions)
@@ -60,7 +78,8 @@ async function _searchUser(
   searchBase,
   usernameAttribute,
   username,
-  attributes = null
+  attributes = null,
+  explicitBufferAttributes = null
 ) {
   let filter = new ldapts.EqualityFilter({
     attribute: usernameAttribute,
@@ -74,6 +93,9 @@ async function _searchUser(
   if (attributes) {
     searchOptions.attributes = attributes
   }
+  if(explicitBufferAttributes) {
+    searchOptions.explicitBufferAttributes = explicitBufferAttributes
+  }
 
   // TODO: we don't support reference yet
   // If the server was able to locate the entry referred to by the baseObject
@@ -98,6 +120,22 @@ async function _searchUser(
     user = searchEntries[0]
   }
 
+  // when attribute endwith ;binary, ldapts returns Buffer, we convert them into base64 string
+  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 user
 }
 
@@ -162,7 +200,8 @@ async function authenticateWithAdmin(
   groupClass,
   groupMemberAttribute = 'member',
   groupMemberUserAttribute = 'dn',
-  attributes = null
+  attributes = null,
+  explicitBufferAttributes = null
 ) {
   let ldapAdminClient
   try {
@@ -183,7 +222,8 @@ async function authenticateWithAdmin(
     userSearchBase,
     usernameAttribute,
     username,
-    attributes
+    attributes,
+    explicitBufferAttributes
   )
   if (!user || !user.dn) {
     ldapOpts.log &&
@@ -233,7 +273,8 @@ async function authenticateWithUser(
   groupClass,
   groupMemberAttribute = 'member',
   groupMemberUserAttribute = 'dn',
-  attributes = null
+  attributes = null,
+  explicitBufferAttributes = null
 ) {
   let ldapUserClient
   try {
@@ -254,7 +295,8 @@ async function authenticateWithUser(
     userSearchBase,
     usernameAttribute,
     username,
-    attributes
+    attributes,
+    explicitBufferAttributes
   )
   if (!user || !user.dn) {
     ldapOpts.log &&
@@ -293,7 +335,8 @@ async function verifyUserExists(
   groupClass,
   groupMemberAttribute = 'member',
   groupMemberUserAttribute = 'dn',
-  attributes = null
+  attributes = null,
+  explicitBufferAttributes = null
 ) {
   let ldapAdminClient
   try {
@@ -314,7 +357,8 @@ async function verifyUserExists(
     userSearchBase,
     usernameAttribute,
     username,
-    attributes
+    attributes,
+    explicitBufferAttributes
   )
   if (!user || !user.dn) {
     ldapOpts.log &&
@@ -376,7 +420,8 @@ async function authenticate(options) {
       options.groupClass,
       options.groupMemberAttribute,
       options.groupMemberUserAttribute,
-      options.attributes
+      options.attributes,
+      options.explicitBufferAttributes
     )
   }
   assert(options.userPassword, 'userPassword must be provided')
@@ -398,7 +443,8 @@ async function authenticate(options) {
       options.groupClass,
       options.groupMemberAttribute,
       options.groupMemberUserAttribute,
-      options.attributes
+      options.attributes,
+      options.explicitBufferAttributes
     )
   }
   assert(options.userDn, 'adminDn/adminPassword OR userDn must be provided')
@@ -414,7 +460,8 @@ async function authenticate(options) {
     options.groupClass,
     options.groupMemberAttribute,
     options.groupMemberUserAttribute,
-    options.attributes
+    options.attributes,
+    options.explicitBufferAttributes
   )
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ldap-authentication",
-  "version": "3.3.3",
+  "version": "3.3.6",
   "description": "A simple async nodejs library for LDAP user authentication",
   "main": "index.js",
   "types": "./index.d.ts",

package/test/binary.spec.js

@@ -0,0 +1,115 @@
+const { Change } = require('ldapts')
+const { authenticate, LdapAuthenticationError } = require('../index.js')
+const ldapts = require('ldapts')
+const { Attribute } = require('ldapts')
+
+const url = process.env.INGITHUB ? 'ldap://localhost:1389' : 'ldap://ldap:1389'
+
+describe('ldap-authentication binary attributes test', () => {
+  const jpegPhotoBase64 =
+    '/9j/4AAQSkZJRgABAQEASABIAAD/2wBDACgcHiMeGSgjISMtKygwPGRBPDc3PHtYXUlkkYCZlo+AjIqgtObDoKrarYqMyP/L2u71////m8H////6/+b9//j/2wBDASstLTw1PHZBQXb4pYyl+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj/wAARCACBAGQDAREAAhEBAxEB/8QAGQAAAwEBAQAAAAAAAAAAAAAAAAECAwQF/8QALRAAAgEDAwMCBQQDAAAAAAAAAAECAxEhBBIxMkFRInEFE2GBsRU0QlJikaH/xAAXAQEBAQEAAAAAAAAAAAAAAAAAAQID/8QAGxEBAQEAAwEBAAAAAAAAAAAAAAERAhIhMUH/2gAMAwEAAhEDEQA/APMIAAKAgChp2AdwAAACBlAQUkmu5RkAAACuAAADsAZQDWQKRA7AL7gAEFCbAQDAYAAXAdwBYAogAAAAgokBgADAEr8Ab09JWqZcdq8yJpjb9Pa5qr/ROy4l6Ga6ZxfvgdoYiemqw6o49yoyAAACCiQKa4AAN9PpnWy3aP5Jbiya9ClRhBJRjby/Ji1qRqRQBMkuwMZSk2trdiys2PPqR2zaNspAAIKE0A+yA201H51TPSuSW4smvTilFJJWSOdbi0RTZQghPgK56nNwzXLXtvx4NxhiUAEABQ0nJpJcgejpkoR2rtyznWo3uRpE5S4i8hfRCrPKm0wLlUUUrgZSruXTD/oROZPISuat1s3GGRQgIKADp0kFNy8pYM2rJrshBQ4M1qNErojTOdFyjZTcfqhKWaqFPObuyAdeKlBfRhcZrT01JzXdWsXWc/U7XF5IVlqWm1waYczKhXKIKEB0aOW2uvDwZvxZ9ejbBlq+CLsZaWrMAckvSgpSW6DQVNKW6ObXRUTVd5BmuKp1M05s2USBmaABpS60Qeg41rqUXeMcszjW61auroliyi7sZaFk1YKirVnSVopyXkqajTNtSv3YouXU/oWM8nHLLZWENFCsBiaAB1aCj86tnpjlko9javBlUVY29SWO4VizNaiVBJcu/m5FJwvyFTGmqct+Como3Juz5EZrnZplLKhWAw5NDZxisW47gen8NpqOncsepmarrIBZwwOWunSf+L4ZmxqVnvI1puoU1nObs347BLS7FZLZ8x27sIwqQcJuMuUaRAGdKN5X8ZKHJu+Qrq02venpbNilnGbDB3UNXHUJ7dqmv4szfA46luVnTbf0ZNFyqUpxcKnpv2kUclWiqT9LvF8O5mtRNnZO+ChSTccAOzsGShVhSlullrhFHPObnNyfLKiAHQW2lKfngqxk3dgSyhwm4TUk3dPDIPV0OrhWltmlGr2fkxYrqrUVVg0+ez8GdHPGhLa0/uaRMFeW1K9wrd6e7vJ2XhFRjKnGqtlNtPyyTB5MrqV28nRFxnf3JgogSqp0FBKzRVZlAEKKyFCbjO6eUQexotaq6UKjtUXf+xz5ccWOmas91u2RKVjHZSlaTe210yoipqHNbY3UfyTVEI7nbyUc+r0vLiuFc1Kjz7WNItSxkmCShAAAgCeXewURbTusNBHs6LWRrpQqO1T8nOzGmtamnG1unK9gM4UknfgqNYxSzZsBuTtiOL2ZKPJ1lFU6zt0yymblRhYonuQD4KEAAOXIUkEa6f8AcQ90Sq92r2+5zioXWvY0jQqJkRXn/EeiHuywcS4NI//Z'
+
+  const baseOptions = {
+    ldapOpts: {
+      url: url,
+    },
+    adminDn: 'cn=read-only-admin,dc=example,dc=com',
+    adminPassword: 'password',
+    verifyUserExists: true,
+    userSearchBase: 'dc=example,dc=com',
+    usernameAttribute: 'uid',
+  }
+
+  it('Add jpegPhoto attribute', async () => {
+    let client = new ldapts.Client({
+      ...baseOptions.ldapOpts,
+    })
+    try {
+      await client.bind(baseOptions.adminDn, baseOptions.adminPassword)
+
+      // https://github.com/ldapts/ldapts/issues/12
+      await client.modify(
+        'cn=gauss,ou=users,dc=example,dc=com',
+        new Change({
+          operation: 'replace',
+          modification: new Attribute({
+            type: 'jpegPhoto',
+            values: [Buffer.from(jpegPhotoBase64, 'base64')],
+          }),
+        })
+      )
+    } finally {
+      await client.unbind()
+    }
+  })
+
+  it('Should return broken jpegPhoto attribute (no attribute selection nor ;binary) - But it really depends on LDAP server, it is not always true. Sometimes a buffer is returned directly.', async () => {
+    let user = await authenticate({
+      ...baseOptions,
+      username: 'gauss',
+    })
+
+    expect(user).toBeTruthy()
+    expect(user.uid).toEqual('gauss')
+    expect(user.sn).toEqual('Bar1')
+    expect(typeof user.uidNumber === 'string').toBe(true)
+    expect(user.uidNumber).toEqual('1000')
+
+    expect(user.jpegPhoto).toBeDefined()
+    // some ldap server returns a string, some ldap server returns a buffer
+    expect(
+      typeof user.jpegPhoto === 'string' || Buffer.isBuffer(user.jpegPhoto)
+    ).toBe(true)
+    if (typeof user.jpegPhoto === 'string') {
+      expect(user.jpegPhoto).not.toEqual(jpegPhotoBase64)
+    }
+    if (Buffer.isBuffer(user.jpegPhoto)) {
+      expect(
+        user.jpegPhoto.equals(Buffer.from(jpegPhotoBase64, 'base64'))
+      ).toBeTrue()
+    }
+  })
+
+  it('Should return nothing in the base64 jpegPhoto (using ;binary)', async () => {
+    let user = await authenticate({
+      ...baseOptions,
+      username: 'gauss',
+      attributes: ['uid', 'sn', 'jpegPhoto;binary'],
+    })
+
+    expect(user).toBeTruthy()
+    expect(user.uid).toEqual('gauss')
+    expect(user.sn).toEqual('Bar1')
+    expect(user.cn).toBeUndefined()
+
+    expect(user.jpegPhoto).toBeUndefined()
+
+    expect(user['jpegPhoto;binary']).toBeDefined()
+    expect(Array.isArray(user['jpegPhoto;binary'])).toBe(true)
+    expect(user['jpegPhoto;binary'].length).toBe(0)
+  })
+
+  it('Should return base64 jpegPhoto (using explicitBufferAttributes)', async () => {
+    let user = await authenticate({
+      ...baseOptions,
+      username: 'gauss',
+      attributes: ['uid', 'sn', 'jpegPhoto'],
+      explicitBufferAttributes: ['jpegPhoto'],
+    })
+
+    expect(user).toBeTruthy()
+    expect(user.uid).toEqual('gauss')
+    expect(user.sn).toEqual('Bar1')
+    expect(user.cn).toBeUndefined()
+
+    expect(user['jpegPhoto;binary']).toBeUndefined()
+
+    expect(user.jpegPhoto).toBeDefined()
+    expect(typeof user.jpegPhoto === 'string').toBe(true)
+    expect(user.jpegPhoto).toEqual(jpegPhotoBase64)
+
+    const buffer = Buffer.from(user.jpegPhoto, 'base64')
+    expect(buffer).toBeDefined()
+    expect(buffer.length).toBeGreaterThan(0)
+  })
+})

package/test/starttls.spec.js

@@ -0,0 +1,126 @@
+const { authenticate, LdapAuthenticationError } = require('../index.js')
+
+const url = process.env.INGITHUB ? 'ldap://localhost:1389' : 'ldap://ldap:1389'
+
+describe('ldap-authentication StartTLS and TLS options test', () => {
+  it('Plain LDAP with tlsOptions in ldapOpts should work (ldap:// protocol)', async () => {
+    // Regression test: Before fix, having tlsOptions with ldap:// URL caused issues
+    // After fix: tlsOptions are properly excluded from Client constructor for ldap:// URLs
+    let options = {
+      ldapOpts: {
+        url: url,
+        tlsOptions: {
+          rejectUnauthorized: false,
+        },
+      },
+      adminDn: 'cn=read-only-admin,dc=example,dc=com',
+      adminPassword: 'password',
+      userPassword: 'password',
+      userSearchBase: 'dc=example,dc=com',
+      usernameAttribute: 'uid',
+      username: 'gauss',
+    }
+
+    let user = await authenticate(options)
+    expect(user).toBeTruthy()
+    expect(user.uid).toEqual('gauss')
+  })
+
+  it('Use an admin user to authenticate with StartTLS (may skip if TLS not configured)', async () => {
+    // Note: This test may not fully succeed if the LDAP server lacks TLS certificates
+    // However, it should NOT fail with the original ECONNRESET bug
+    let options = {
+      ldapOpts: {
+        url: url,
+        tlsOptions: {
+          rejectUnauthorized: false,
+          minVersion: 'TLSv1.2',
+        },
+      },
+      starttls: true,
+      adminDn: 'cn=read-only-admin,dc=example,dc=com',
+      adminPassword: 'password',
+      userPassword: 'password',
+      userSearchBase: 'dc=example,dc=com',
+      usernameAttribute: 'uid',
+      username: 'gauss',
+    }
+
+    try {
+      let user = await authenticate(options)
+      // If this succeeds, StartTLS is fully working!
+      expect(user).toBeTruthy()
+      expect(user.uid).toEqual('gauss')
+    } catch (error) {
+      // Expected if StartTLS is not configured on the server
+      // The critical check: should NOT be the original ECONNRESET bug
+      if (error.code === 'ECONNRESET' && 
+          error.message && error.message.includes('Client network socket disconnected before secure TLS connection')) {
+        fail('ECONNRESET bug detected: tlsOptions should NOT be passed to Client constructor when using ldap:// URL')
+      }
+      // Other errors are acceptable (e.g., server doesn't support StartTLS)
+      expect(error).toBeTruthy()
+    }
+  })
+
+  it('Use a regular user to authenticate with StartTLS (self mode)', async () => {
+    let options = {
+      ldapOpts: {
+        url: url,
+        tlsOptions: {
+          rejectUnauthorized: false,
+          minVersion: 'TLSv1.2',
+        },
+      },
+      starttls: true,
+      userDn: 'cn=einstein,ou=users,dc=example,dc=com',
+      userPassword: 'password',
+      userSearchBase: 'dc=example,dc=com',
+      usernameAttribute: 'uid',
+      username: 'einstein',
+    }
+
+    try {
+      let user = await authenticate(options)
+      expect(user).toBeTruthy()
+      expect(user.uid).toEqual('einstein')
+    } catch (error) {
+      if (error.code === 'ECONNRESET' && 
+          error.message && error.message.includes('Client network socket disconnected before secure TLS connection')) {
+        fail('ECONNRESET bug detected: tlsOptions should NOT be passed to Client constructor when using ldap:// URL')
+      }
+      expect(error).toBeTruthy()
+    }
+  })
+
+  it('Verify user exists with StartTLS', async () => {
+    let options = {
+      ldapOpts: {
+        url: url,
+        tlsOptions: {
+          rejectUnauthorized: false,
+          minVersion: 'TLSv1.2',
+        },
+      },
+      starttls: true,
+      adminDn: 'cn=read-only-admin,dc=example,dc=com',
+      adminPassword: 'password',
+      verifyUserExists: true,
+      userSearchBase: 'dc=example,dc=com',
+      usernameAttribute: 'uid',
+      username: 'gauss',
+    }
+
+    try {
+      let user = await authenticate(options)
+      expect(user).toBeTruthy()
+      expect(user.uid).toEqual('gauss')
+    } catch (error) {
+      if (error.code === 'ECONNRESET' && 
+          error.message && error.message.includes('Client network socket disconnected before secure TLS connection')) {
+        fail('ECONNRESET bug detected: tlsOptions should NOT be passed to Client constructor when using ldap:// URL')
+      }
+      expect(error).toBeTruthy()
+    }
+  })
+})

package/test/test.spec.js

@@ -144,7 +144,7 @@ describe('ldap-authentication test', () => {
     let user = await authenticate(options)
     expect(user).toBeTruthy()
     expect(user.groups.length).toBeGreaterThan(0)
-    expect(user.groups[0].dn).toEqual('cn=科学A部,ou=users,dc=example,dc=com')
+    expect(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 = {
@@ -165,10 +165,10 @@ describe('ldap-authentication test', () => {
     let user = await authenticate(options)
     expect(user).toBeTruthy()
     expect(user.groups.length).toBeGreaterThan(0)
-    expect(user.groups[0].dn).toEqual('cn=科学A部,ou=users,dc=example,dc=com')
+    expect(user.groups[0].dn).toEqual('cn=科学A部,ou=groups,dc=example,dc=com')
     // backward compatible with 3.2
     expect(user.groups[0].objectName).toEqual(
-      'cn=科学A部,ou=users,dc=example,dc=com'
+      '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 () => {