LDAPts


Providing an API to access LDAP directory servers from Node.js programs.

Table of Contents

- API Details
- Create a client
- Specifying Controls
- bind
- startTLS
- add
- compare
- del
- exop
- modify
- Change
- modifyDN
- search
- Filter Strings
- Return buffer for specific attribute
- searchPaginated
- unbind
- Usage Examples
- Authenticate example
- Search example
- Delete Active Directory entry example
- Configuring Secure Connections
- Common Errors
- Development
- Start test OpenLDAP server
- Close test OpenLDAP server

API details

$3

The code to create a new client looks like:

``ts
import { Client } from 'ldapts';

const client = new Client({
url: 'ldaps://ldap.jumpcloud.com',
timeout: 0,
connectTimeout: 0,
tlsOptions: {
minVersion: 'TLSv1.2',
},
strictDN: true,
});
`

You can use ldap:// or ldaps://; the latter would connect over SSL (note
that this will not use the LDAP TLS extended operation, but literally an SSL
connection to port 636, as in LDAP v2). The full set of options to create a
client is:

| Attribute | Description |
| -------------- | ------------------------------------------------------------------------------------------ |
| url | A valid LDAP URL (proto/host/port only) |
| timeout | Milliseconds client should let operations live for before timing out (Default: Infinity) |
| connectTimeout | Milliseconds client should wait before timing out on TCP connections (Default: OS default) |
| tlsOptions | TLS connect() options |
| strictDN | Force strict DN parsing for client methods (Default is true) |

$3

Single or an array of Control objects can be added to various operations like the following:

`ts
import { Control } from 'ldapts/controls';

const { searchEntries, searchReferences } = await client.search(
searchDN,
{
filter: '(mail=peter.parker@marvel.com)',
},
new Control('1.2.840.113556.1.4.417'),
);
`

You can also subclass Control for finer control over how data is parsed and written.
Look at PagedResultsControl for an example.

$3

bind(dnOrSaslMechanism, [password], [controls])

Performs a bind operation against the LDAP server.

Arguments:

| Argument | Description |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| dnOrSaslMechanism (string) | The name (DN) of the directory object that the client wishes to bind as or the SASL mechanism (PLAIN, EXTERNAL) |
| [password] (string) | Password for the target bind DN. For SASL this is instead an optional set of encoded SASL credentials. |
| [controls] (Control|Control[]) | Optional Control object or array of Control objects |

Simple Example:

`ts
await client.bind('cn=root', 'secret');
`

SASL Example:

`ts
// No credentials
await client.bind('EXTERNAL');

// With credentials
const credentials = '...foo...';
await client.bind('PLAIN', credentials);
`

$3

startTLS(options, [controls])

Performs a StartTLS extended operation against the LDAP server to initiate a TLS-secured communication channel over an
otherwise clear-text connection.

Arguments:

| Argument | Description |
| ------------------------------------- | ----------------------------------------------------------------------------------------- |
| options (object) | TLS connect() options |
| [controls] (Control|Control[]) | Optional Control object or array of Control objects |

Example:

`ts
await client.startTLS({
ca: [fs.readFileSync('mycacert.pem')],
});
`

$3

add(dn, entry, [controls])

Performs an add operation against the LDAP server.

Allows you to add an entry (as a js object or array of Attributes), and as always,
controls are optional.

Arguments:

| Argument | Description |
| ------------------------------------- | ------------------------------------------------------- |
| dn (string) | The DN of the entry to add |
| entry (object|Attribute[]) | The set of attributes to include in that entry |
| [controls] (Control|Control[]) | Optional Control object or array of Control objects |

Example:

`ts
var entry = {
cn: 'foo',
sn: 'bar',
email: ['foo@bar.com', 'foo1@bar.com'],
objectclass: 'fooPerson',
};
await client.add('cn=foo, o=example', entry);
`

$3

compare(dn, attribute, value, [controls])

Performs an LDAP compare operation with the given attribute and value against
the entry referenced by dn.

Arguments:

| Argument | Description |
| ------------------------------------- | ----------------------------------------------------------------------- |
| dn (string) | The DN of the entry in which the comparison is to be made |
| attribute (string) | The Name of the attribute in which the comparison is to be made |
| value (string) | The Attribute Value Assertion to try to find in the specified attribute |
| [controls] (Control|Control[]) | Optional Control object or array of Control objects |

Returns:
(boolean): Returns true if the target entry exists and does contain the specified attribute value; otherwise false

Example:

`ts
const hasValue = await client.compare('cn=foo, o=example', 'sn', 'bar');
`

$3

del(dn, [controls])

Deletes an entry from the LDAP server.

Arguments:

| Argument | Description |
| ------------------------------------- | ------------------------------------------------------- |
| dn (string) | The DN of the entry to delete |
| [controls] (Control|Control[]) | Optional Control object or array of Control objects |

Example:

`ts
await client.del('cn=foo, o=example');
`

$3

exop(oid, [value], [controls])

Performs an LDAP extended operation against an LDAP server.

Arguments:

| Argument | Description |
| ------------------------------------- | ------------------------------------------------------- |
| oid (string) | Object identifier representing the type of request |
| [value] (string) | Optional value - based on the type of operation |
| [controls] (Control|Control[]) | Optional Control object or array of Control objects |

Example (performs an LDAP 'whoami' extended op):

`ts
const { value } = await client.exop('1.3.6.1.4.1.4203.1.11.3');
`

$3

modify(name, changes, [controls])

Performs an LDAP modify operation against the LDAP server. This API requires
you to pass in a Change object, which is described below. Note that you can
pass in a single Change or an array of Change objects.

Arguments:

| Argument | Description |
| ------------------------------------- | ------------------------------------------------------- |
| dn (string) | The DN of the entry to modify |
| changes (Change|Change[]) | The set of changes to make to the entry |
| [controls] (Control|Control[]) | Optional Control object or array of Control objects |

Example (update multiple attributes):

`ts
import { Attribute, Change } from 'ldapts';

await client.modify('cn=foo, o=example', [
new Change({ operation: 'replace', modification: new Attribute({ type: 'title', values: ['web tester'] }) }),
new Change({ operation: 'replace', modification: new Attribute({ type: 'displayName', values: ['John W Doe'] }) }),
]);
`

Example (update binary attribute):

`ts
import { Attribute, Change } from 'ldapts';

const thumbnailPhotoBuffer = await fs.readFile(path.join(__dirname, './groot_100.jpg'));

var change = new Change({
operation: 'replace',
modification: new Attribute({
type: 'thumbnailPhoto;binary',
values: [thumbnailPhotoBuffer],
}),
});

await client.modify('cn=foo, o=example', change);
`

#### Change

Change({ operation, modification })

A Change object maps to the LDAP protocol of a modify change, and requires you
to set the operation and modification.

Arguments:

| Argument | Description |
| ------------------------------------------ | ------------------------------------------- |
| operation (replace|add|delete) | _See table below_ |
| modification (Attribute) | Attribute details to add, remove, or update |

Operations:

| Value | Description |
| --------- | --------------------------------------------------------------------------------------------------------------------- |
| replace | Replaces the attribute referenced in modification. If the modification has no values, it is equivalent to a delete. |
| add | Adds the attribute value(s) referenced in modification. The attribute may or may not already exist. |
| delete | Deletes the attribute (and all values) referenced in modification. |

$3

modifyDN(dn, newDN, [controls])

Performs an LDAP modifyDN (rename) operation against an entry in the LDAP
server. A couple points with this client API:

- There is no ability to set "keep old dn." It's always going to flag the old
dn to be purged.
- The client code will automatically figure out if the request is a "new
superior" request ("new superior" means move to a different part of the tree,
as opposed to just renaming the leaf).

Arguments:

| Argument | Description |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| dn (string) | The DN of the entry to rename |
| newDN (string) | The new RDN to use assign to the entry. It may be the same as the current RDN if you only intend to move the entry beneath a new parent. If the new RDN includes any attribute values that aren’t already in the entry, the entry will be updated to include them. |
| [controls] (Control|Control[]) | Optional Control object or array of Control objects |

Example:

`ts
await client.modifyDN('cn=foo, o=example', 'cn=bar');
`

$3

search(baseDN, options, [controls])

Performs a search operation against the LDAP server.

The search operation is more complex than the other operations, so this one
takes an options object for all the parameters.

Arguments:

| Argument | Description |
| ------------------------------------- | ---------------------------------------------------------------- |
| baseDN (string) | The base of the subtree in which the search is to be constrained |
| options (object) | _See table below_ |
| [controls] (Control|Control[]) | Optional Control object or array of Control objects |

Options:

| Attribute | Description |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [scope=sub] (string) |

• base - Indicates that only the entry specified as the search base should be considered. None of its subordinates will be considered.
• one - Indicates that only the immediate children of the entry specified as the search base should be considered. The base entry itself should not be considered, nor any descendants of the immediate children of the base entry.
• sub - Indicates that the entry specified as the search base, and all of its subordinates to any depth, should be considered.
• children - Indicates that the entry specified by the search base should not be considered, but all of its subordinates to any depth should be considered.

• never - Never dereferences entries, returns alias objects instead. The alias contains the reference to the real entry.
• always - Always returns the referenced entries, not the alias object.
• search - While searching subordinates of the base object, dereferences any alias within the search scope. Dereferenced objects become the bases of further search scopes where the Search operation is also applied by the server. The server should eliminate duplicate entries that arise due to alias dereferencing while searching.
• find - Dereferences aliases in locating the base object of the search, but not when searching subordinates of the base object.

`ts
const { searchEntries, searchReferences } = await client.search(searchDN, {
filter: '(mail=peter.parker@marvel.com)',
});
`

Please see Client tests for more search examples

$3

search(baseDN, options, [controls])

Performs a search operation against the LDAP server and retrieve results in a paginated way.

The searchPagination the same options with search method but returns an iterator.

Example:

`ts
const paginator = client.searchPaginated('o=5be4c382c583e54de6a3ff52,dc=jumpcloud,dc=com', {
filter: 'objectclass=*',
paged: {
pageSize: 10,
},
});

let total = 0;
for await (const searchResult of paginator) {
total += searchResult.searchEntries.length;
console.log(searchResult.searchEntries);
}

console.log(total results: ${total});
`

#### Filter Strings

The easiest way to write search filters is to write them compliant with RFC2254,
which is "The string representation of LDAP search filters."

Assuming you don't really want to read the RFC, search filters in LDAP are
basically are a "tree" of attribute/value assertions, with the tree specified
in prefix notation. For example, let's start simple, and build up a complicated
filter. The most basic filter is equality, so let's assume you want to search
for an attribute email with a value of foo@bar.com. The syntax would be:

`ts
const filter = (email=foo@bar.com);
`

ldapts requires all filters to be surrounded by '()' blocks. Ok, that was easy.
Let's now assume that you want to find all records where the email is actually
just anything in the "@bar.com" domain and the location attribute is set to
Seattle:

`ts
const filter = (&(email=*@bar.com)(l=Seattle));
`

Now our filter is actually three LDAP filters. We have an and filter (single
amp &), an equality filter (the l=Seattle), and a substring filter.
Substrings are wildcard filters. They use * as the wildcard. You can put more
than one wildcard for a given string. For example you could do (email=@bar.com)
to match any email of @bar.com or its subdomains like "".

Now, let's say we also want to set our filter to include a
specification that either the employeeType _not_ be a manager nor a secretary:

`ts
const filter = (&(email=*@bar.com)(l=Seattle)(!(|(employeeType=manager)(employeeType=secretary))));
`

The not character is represented as a !, the or as a single pipe |.
It gets a little bit complicated, but it's actually quite powerful, and lets you
find almost anything you're looking for.

#### Return buffer for specific attribute

Sometimes you may want to get a buffer back instead of a string for an attribute value. Depending on the server software,
you may be able to append ;binary
(the binary attribute subtype) to the attribute name,
to have the value returned as a Buffer.

`ts
const searchResults = await ldapClient.search('ou=Users,o=5be4c382c583e54de6a3ff52,dc=jumpcloud,dc=com', {
filter: '(mail=peter.parker@marvel.com)',
attributes: ['jpegPhoto;binary'],
});
`

However, some servers are very strict when it comes to the binary attribute subtype and will only acknowledge it if
there is an associated AN.1 type or valid BER encoding. In those cases, you can tell ldapts to explicitly return a
Buffer for an attribute:

`ts
const searchResult = await client.search('ou=Users,o=5be4c382c583e54de6a3ff52,dc=jumpcloud,dc=com', {
filter: '(mail=peter.parker@marvel.com)',
explicitBufferAttributes: ['jpegPhoto'],
});
`

$3

unbind()

Used to indicate that the client wants to close the connection to the directory server.

Example:

`ts
await client.unbind();
`

Usage Examples

$3

`ts
const { Client } = require('ldapts');

const url = 'ldap://ldap.forumsys.com:389';
const bindDN = 'cn=read-only-admin,dc=example,dc=com';
const password = 'password';

const client = new Client({
url,
});

let isAuthenticated;
try {
await client.bind(bindDN, password);
isAuthenticated = true;
} catch (ex) {
isAuthenticated = false;
} finally {
await client.unbind();
}
`

$3

`ts
const { Client } = require('ldapts');

const url = 'ldaps://ldap.jumpcloud.com';
const bindDN = 'uid=tony.stark,ou=Users,o=5be4c382c583e54de6a3ff52,dc=jumpcloud,dc=com';
const password = 'MyRedSuitKeepsMeWarm';
const searchDN = 'ou=Users,o=5be4c382c583e54de6a3ff52,dc=jumpcloud,dc=com';

const client = new Client({
url,
tlsOptions: {
rejectUnauthorized: args.rejectUnauthorized,
},
});

try {
await client.bind(bindDN, password);

const { searchEntries, searchReferences } = await client.search(searchDN, {
scope: 'sub',
filter: '(mail=peter.parker@marvel.com)',
});
} catch (ex) {
throw ex;
} finally {
await client.unbind();
}
`

$3

`ts
const { Client } = require('ldapts');

const url = 'ldap://127.0.0.1:1389';
const bindDN = 'uid=foo,dc=example,dc=com';
const password = 'bar';
const dnToDelete = 'uid=foobar,dc=example,dc=com';

const client = new Client({
url,
});

try {
await client.bind(bindDN, password);

await client.del(dnToDelete);
} catch (ex) {
if (ex instanceof InvalidCredentialsError) {
// Handle authentication specifically
}

throw ex;
} finally {
await client.unbind();
}
`

using declaration with Typescript

For more details look have a look at using Declarations and Explicit Resource Management

`ts
{
await using client = new Client({
url: 'ldap://127.0.0.1:1389',
});
await client.bind(bindDN, password);
}
// unbind is called
`

Configuring Secure Connections

When configuring secure connections in ldapts, it is important to choose the appropriate TLS method (via the Client constructor or client.startTLS) based
on your LDAP server's requirements. Prefer connecting securely from the Client constructor if the server supports LDAP over SSL. If that's not available but the
connection can be upgraded to a secure connection, then connect insecurely and call startTLS to upgrade the connection to be secure.

$3

If the LDAP server requires ldaps:// (LDAP over SSL), specify ldaps:// in the url and provide tlsOptions to the Client constructor to handle certificate validation.
This will establish a secure connection to the LDAP server over TLS from the moment the LDAP client is instantiated.

Example:

`ts
import { Client } from 'ldapts';
import fs from 'fs';
const client = new Client({
url: 'ldaps://ldap.example.com',
tlsOptions: {
ca: [fs.readFileSync('/path/to/ca-cert.pem')],
},
});
`

$3

If the server is unable to support LDAP over SSL but supports STARTTLS, the connection can be upgraded to a secure connection.
Connect to the server using ldap:// and call client.startTLS() to upgrade to a secure connection.

Example:

`ts
import { Client } from 'ldapts';
import fs from 'fs';
const client = new Client({ url: 'ldap://ldap.example.com' });
async function connectWithStartTLS() {
await client.startTLS({
ca: [fs.readFileSync('/path/to/ca-cert.pem')],
});
}
`

Common Errors

$3

Cause: There is a mismatch between the LDAP protocol being used by the client and server. For example,
The server expects an ldaps:// connection, but the client uses ldap:// without upgrading to TLS.
Alternatively, the client is configured to use LDAP over SSL, but is connecting to the server using the ldap:// protocol.

Solution: Review the configuration options above and ensure that the client and server are configured to use the same protocol.
If connecting to a ldap:// address, call startTLS() to upgrade the connection. If connecting to an ldaps:// protocol,
provide the TLS options in the Client constructor.

$3

Cause: The LDAP server's certificate is untrusted, often due to a self-signed certificate or an incomplete certificate chain.

Solution(s):

- Provide the CA certificate to establish trust:

`ts
import fs from 'fs';

const client = new Client({
url: 'ldaps://ldap.example.com',
tlsOptions: {
ca: [fs.readFileSync('/path/to/ca-cert.pem')],
},
});
`

- Allow self-signed certificates (not recommended for production):

`ts
const client = new Client({
url: 'ldaps://ldap.example.com',
tlsOptions: {
rejectUnauthorized: false, // Allow untrusted certificates
},
});
`

$3

Cause: The LDAP server is not reachable at the specified host and port, or the server is not listening on the expected protocol.

Solution:

- Verify the server address, port, and protocol in the url.
- Ensure the server is running and accessible.
- Check firewall rules to allow connections on the required port (636 for ldaps, 389 for ldap).

$3

Cause: The server takes too long to respond to the TLS handshake due to network latency or misconfiguration.

Solution:

- Check the LDAP server's performance.
- Verify TLS configuration (e.g., ciphers and protocols) on both client and server.
- Increase the timeout if necessary:

`ts
const client = new Client({
url: 'ldaps://ldap.example.com',
timeout: 30000, // 30 seconds
});
`

$3

Cause: The server uses a certificate signed by an untrusted CA.

Solution: Provide the CA certificate:

`ts
import fs from 'fs';

const client = new Client({
url: 'ldaps://ldap.example.com',
tlsOptions: {
ca: [fs.readFileSync('/path/to/ca-cert.pem')],
},
});
`

$3

Cause: The LDAP server is using a self-signed certificate without an intermediate CA.

Solution(s):

- Use the server's certificate as the trusted CA:

`ts
import fs from 'fs';

const client = new Client({
url: 'ldaps://ldap.example.com',
tlsOptions: {
ca: [fs.readFileSync('/path/to/server-cert.pem')],
},
});
`

- Allow self-signed certificates (not recommended for production):

`ts
const client = new Client({
url: 'ldaps://ldap.example.com',
tlsOptions: {
rejectUnauthorized: false, // Allow self-signed certificates
},
});
`

Development

$3

Run generate-certs.js

`sh
node tests/data/generate-certs.mjs
`

$3

`shell
docker compose up -d
`

$3

`shell
docker compose down
``