Browse project docs

TLS and StartTLS

Secure ldapjs-community client connections with certificate-validated LDAPS or a StartTLS upgrade.

On this page

ldapjs-community supports encrypted client connections through an ldaps:// URL or by upgrading an existing ldap:// connection with starttls.

Validate the server certificate

Provide the issuing CA when it is not already trusted by the runtime. Do not disable verification with rejectUnauthorized: false.

LDAPS

Pass TLS options when creating a client with an ldaps:// URL:

javascript
const fs = require('node:fs')
const ldap = require('ldapjs')

const client = ldap.createClient({
  url: process.env.LDAPS_URL,
  tlsOptions: {
    ca: [fs.readFileSync(process.env.LDAP_CA_FILE)]
  }
})

client.on('error', (err) => console.error('LDAPS error:', err))

client.bind(process.env.LDAP_BIND_DN, process.env.LDAP_PASSWORD, (err) => {
  if (err) {
    client.destroy()
    throw err
  }

  console.log('Secure bind succeeded')
  client.unbind()
})

StartTLS

Create an ldap:// client, upgrade it, then bind:

javascript
const fs = require('node:fs')
const ldap = require('ldapjs')

const client = ldap.createClient({ url: process.env.LDAP_URL })

client.on('error', (err) => console.error('LDAP error:', err))

client.starttls({
  ca: [fs.readFileSync(process.env.LDAP_CA_FILE)]
}, (tlsError) => {
  if (tlsError) {
    client.destroy()
    throw tlsError
  }

  client.bind(process.env.LDAP_BIND_DN, process.env.LDAP_PASSWORD, (bindError) => {
    if (bindError) {
      client.destroy()
      throw bindError
    }

    console.log('StartTLS bind succeeded')
    client.unbind()
  })
})

Operational checks

  • Match the URL and port to the intended transport.
  • Trust the correct CA chain and ensure the server name matches its certificate.
  • Treat a failed TLS upgrade as a hard failure; do not continue with a plaintext bind.
  • Test certificate rotation and failure behavior in the deployment environment.

For protocol background, read LDAPS and TLS and StartTLS explained.

Sources