ldapjs Server API

Create a server

The code to create a new server looks like:

const server = ldap.createServer();

The full list of options is:

||log||You can optionally pass in a Bunyan compatible logger instance the client will use to acquire a child logger.|| ||certificate||A PEM-encoded X.509 certificate; will cause this server to run in TLS mode.|| ||key||A PEM-encoded private key that corresponds to certificate for SSL.||

Note On Logger

The passed in logger is expected to conform to the Log4j standard API. Internally, abstract-logging is used to implement the interface. As a result, no log messages will be generated unless an external logger is supplied.

Known compatible loggers are:

• Bunyan
• Pino

Properties on the server object

maxConnections

Set this property to reject connections when the server's connection count gets high.

connections (getter only) - DEPRECATED

The number of concurrent connections on the server. This property is deprecated, please use server.getConnections() instead.

url

Returns the fully qualified URL this server is listening on. For example: ldaps://10.1.2.3:1636. If you haven't yet called listen, it will always return ldap://localhost:389.

Event: 'close'

function() {}

Emitted when the server closes.

Listening for requests

The LDAP server API wraps up and mirrors the node.js server.listen family of APIs.

After calling listen, the property url on the server object itself will be available.

Example:

 server.listen(389, '127.0.0.1', function() {
   console.log('LDAP server listening at: ' + server.url);
 });

Port and Host

listen(port, [host], [callback])

Begin accepting connections on the specified port and host. If the host is omitted, the server will accept connections directed to any IPv4 address (INADDR_ANY).

This function is asynchronous. The last parameter callback will be called when the server has been bound.

Unix Domain Socket

listen(path, [callback])

Start a UNIX socket server listening for connections on the given path.

This function is asynchronous. The last parameter callback will be called when the server has been bound.

File descriptor

listenFD(fd)

Start a server listening for connections on the given file descriptor.

This file descriptor must have already had the bind(2) and listen(2) system calls invoked on it. Additionally, it must be set non-blocking; try fcntl(fd, F_SETFL, O_NONBLOCK).

Inspecting server state

server.getConnections(callback)

The LDAP server API mirrors the Node.js server.getConnections API. Callback should take two arguments err and count.

Routes

The LDAP server API is meant to be the LDAP-equivalent of the express/restify paradigm of programming. Essentially every method is of the form OP(req, res, next) where OP is one of bind, add, del, etc. You can chain handlers together by calling next() and ordering your functions in the definition of the route. For example:

function authorize(req, res, next) {
  if (!req.connection.ldap.bindDN.equals('cn=root'))
    return next(new ldap.InsufficientAccessRightsError());

  return next();
}

server.search('o=example', authorize, function(req, res, next) { ... });

Note that ldapjs is also slightly different, since it's often going to be backed to a DB-like entity, in that it also has an API where you can pass in a 'backend' object. This is necessary if there are persistent connection pools, caching, etc. that need to be placed in an object.

For example ldapjs-riak is a complete implementation of the LDAP protocol over Riak. Getting an LDAP server up with riak looks like:

const ldap = require('ldapjs');
const ldapRiak = require('ldapjs-riak');

const server = ldap.createServer();
const backend = ldapRiak.createBackend({
  "host": "localhost",
  "port": 8098,
  "bucket": "example",
  "indexes": ["l", "cn"],
  "uniqueIndexes": ["uid"],
  "numConnections": 5
});

server.add("o=example",
           backend,
           backend.add());
...

The first parameter to an ldapjs route is always the point in the tree to mount the handler chain at. The second argument is optionally a backend object. After that you can pass in an arbitrary combination of functions in the form f(req, res, next) or arrays of functions of the same signature (ldapjs will unroll them).

Unlike HTTP, LDAP operations do not have a heterogeneous wire format, so each operation requires specific methods/fields on the request/response objects. However, there is a .use() method availabe, similar to that on express/connect, allowing you to chain up "middleware":

server.use(function(req, res, next) {
  console.log('hello world');
  return next();
});

Common Request Elements

All request objects have the dn getter on it, which is "context-sensitive" and returns the point in the tree that the operation wants to operate on. The LDAP protocol itself sadly doesn't define operations this way, and has a unique name for just about every op. So, ldapjs calls it dn. The DN object itself is documented at DN.

All requests have an optional array of Control objects. Control will have the properties type (string), criticality (boolean), and optionally, a string value.

All request objects will have a connection object, which is the net.Socket associated to this request. Off the connection object is an ldap object. The most important property to pay attention to is the bindDN property which will be an instance of an ldap.DN object. This is what the client authenticated as on this connection. If the client didn't bind, then a DN object will be there defaulted to cn=anonymous.

Additionally, request will have a logId parameter you can use to uniquely identify the request/connection pair in logs (includes the LDAP messageID).

Common Response Elements

All response objects will have an end method on them. By default, calling res.end() with no arguments will return SUCCESS (0x00) to the client (with the exception of compare which will return COMPARE_TRUE (0x06)). You can pass in a status code to the end() method to return an alternate status code.

However, it's more common/easier to use the return next(new LDAPError()) pattern, since ldapjs will fill in the extra LDAPResult fields like matchedDN and error message for you.

Errors

ldapjs includes an exception hierarchy that directly corresponds to the RFC list of error codes. The complete list is documented in errors. But the paradigm is something defined like CONSTRAINT_VIOLATION in the RFC would be ConstraintViolationError in ldapjs. Upon calling next(new LDAPError()), ldapjs will stop calling your handler chain. For example:

server.search('o=example',
  (req, res, next) => { return next(); },
  (req, res, next) => { return next(new ldap.OperationsError()); },
  (req, res, next) => { res.end(); }
);

In the code snipped above, the third handler would never get invoked.

Bind

Adds a mount in the tree to perform LDAP binds with. Example:

server.bind('ou=people, o=example', (req, res, next) => {
  console.log('bind DN: ' + req.dn.toString());
  console.log('bind PW: ' + req.credentials);
  res.end();
});

BindRequest

BindRequest objects have the following properties:

version

The LDAP protocol version the client is requesting to run this connection on. Note that ldapjs only supports LDAP version 3.

name

The DN the client is attempting to bind as (note this is the same as the dn property).

authentication

The method of authentication. Right now only simple is supported.

credentials

The credentials to go with the name/authentication pair. For simple, this will be the plain-text password.

BindResponse

No extra methods above an LDAPResult API call.

Add

Adds a mount in the tree to perform LDAP adds with.

server.add('ou=people, o=example', (req, res, next) => {
  console.log('DN: ' + req.dn.toString());
  console.log('Entry attributes: ' + req.toObject().attributes);
  res.end();
});

AddRequest

AddRequest objects have the following properties:

entry

The DN the client is attempting to add (this is the same as the dn property).

attributes

The set of attributes in this entry. This will be an array of Attribute objects (which have a type and an array of values). This directly maps to how the request came in off the wire. It's likely you'll want to use toObject() and iterate that way, since that will transform an AddRequest into a standard JavaScript object.

toObject()

This operation will return a plain JavaScript object from the request that looks like:

{
  dn: 'cn=foo, o=example',  // string, not DN object
  attributes: {
    cn: ['foo'],
    sn: ['bar'],
    objectclass: ['person', 'top']
  }
}

AddResponse

No extra methods above an LDAPResult API call.

Search

Adds a handler for the LDAP search operation.

server.search('o=example', (req, res, next) => {
  console.log('base object: ' + req.dn.toString());
  console.log('scope: ' + req.scope);
  console.log('filter: ' + req.filter.toString());
  res.end();
});

SearchRequest

SearchRequest objects have the following properties:

baseObject

The DN the client is attempting to start the search at (equivalent to dn).

scope

(string) one of:

• base
• one
• sub

derefAliases

An integer (defined in the LDAP protocol). Defaults to '0' (meaning never deref).

sizeLimit

The number of entries to return. Defaults to '0' (unlimited). ldapjs doesn't currently automatically enforce this, but probably will at some point.

timeLimit

Maximum amount of time the server should take in sending search entries. Defaults to '0' (unlimited).

typesOnly

Whether to return only the names of attributes, and not the values. Defaults to 'false'. ldapjs will take care of this for you.

filter

The filter object that the client requested. Notably this has a matches() method on it that you can leverage. For an example of introspecting a filter, take a look at the ldapjs-riak source.

attributes

An optional list of attributes to restrict the returned result sets to. ldapjs will automatically handle this for you.

SearchResponse

send(entry)

Allows you to send a SearchEntry object. You do not need to explicitly pass in a SearchEntry object, and can instead just send a plain JavaScript object that matches the format used from AddRequest.toObject().

server.search('o=example', (req, res, next) => {
  const obj = {
    dn: 'o=example',
    attributes: {
      objectclass: ['top', 'organization'],
      o: ['example']
    }
  };

  if (req.filter.matches(obj))
    res.send(obj)

  res.end();
});

modify

Allows you to handle an LDAP modify operation.

server.modify('o=example', (req, res, next) => {
  console.log('DN: ' + req.dn.toString());
  console.log('changes:');
  for (const c of req.changes) {
    console.log('  operation: ' + c.operation);
    console.log('  modification: ' + c.modification.toString());
  }
  res.end();
});

ModifyRequest

ModifyRequest objects have the following properties:

object

The DN the client is attempting to update (this is the same as the dn property).

changes

An array of Change objects the client is attempting to perform. See below for details on the Change object.

Change

The Change object will have the following properties:

operation

A string, and will be one of: 'add', 'delete', or 'replace'.

modification

Will be an Attribute object, which will have a 'type' (string) field, and 'vals', which will be an array of string values.

ModifyResponse

No extra methods above an LDAPResult API call.

del

Allows you to handle an LDAP delete operation.

server.del('o=example', (req, res, next) => {
  console.log('DN: ' + req.dn.toString());
  res.end();
});

DeleteRequest

entry

The DN the client is attempting to delete (this is the same as the dn property).

DeleteResponse

No extra methods above an LDAPResult API call.

compare

Allows you to handle an LDAP compare operation.

server.compare('o=example', (req, res, next) => {
  console.log('DN: ' + req.dn.toString());
  console.log('attribute name: ' + req.attribute);
  console.log('attribute value: ' + req.value);
  res.end(req.value === 'foo');
});

CompareRequest

entry

The DN the client is attempting to compare (this is the same as the dn property).

attribute

The string name of the attribute to compare values of.

value

The string value of the attribute to compare.

CompareResponse

The end() method for compare takes a boolean, as opposed to a numeric code (you can still pass in a numeric LDAP status code if you want). Beyond that, there are no extra methods above an LDAPResult API call.

modifyDN

Allows you to handle an LDAP modifyDN operation.

server.modifyDN('o=example', (req, res, next) => {
  console.log('DN: ' + req.dn.toString());
  console.log('new RDN: ' + req.newRdn.toString());
  console.log('deleteOldRDN: ' + req.deleteOldRdn);
  console.log('new superior: ' +
    (req.newSuperior ? req.newSuperior.toString() : ''));

  res.end();
});

ModifyDNRequest

entry

The DN the client is attempting to rename (this is the same as the dn property).

newRdn

The leaf RDN the client wants to rename this entry to. This will be a DN object.

deleteOldRdn

Whether or not to delete the old RDN (i.e., rename vs copy). Defaults to 'true'.

newSuperior

Optional (DN). If the modifyDN operation wishes to relocate the entry in the tree, the newSuperior field will contain the new parent.

ModifyDNResponse

No extra methods above an LDAPResult API call.

exop

Allows you to handle an LDAP extended operation. Extended operations are pretty much arbitrary extensions, by definition. Typically the extended 'name' is an OID, but ldapjs makes no such restrictions; it just needs to be a string. Unlike the other operations, extended operations don't map to any location in the tree, so routing here will be exact match, as opposed to subtree.

// LDAP whoami
server.exop('1.3.6.1.4.1.4203.1.11.3', (req, res, next) => {
  console.log('name: ' + req.name);
  console.log('value: ' + req.value);
  res.value = 'u:xxyyz@EXAMPLE.NET';
  res.end();
  return next();
});

ExtendedRequest

name

Will always be a match to the route-defined name. Clients must include this in their requests.

value

Optional string. The arbitrary blob the client sends for this extended operation.

ExtendedResponse

name

The name of the extended operation. ldapjs will automatically set this.

value

The arbitrary (string) value to send back as part of the response.

unbind

ldapjs by default provides an unbind handler that just disconnects the client and cleans up any internals (in ldapjs core). You can override this handler if you need to clean up any items in your backend, or perform any other cleanup tasks you need to.

server.unbind((req, res, next) => {
  res.end();
});

Note that the LDAP unbind operation actually doesn't send any response (by definition in the RFC), so the UnbindResponse is really just a stub that ultimately calls net.Socket.end() for you. There are no properties available on either the request or response objects, except, of course, for end() on the response.

ldapjs Client API

Create a client

The code to create a new client looks like:

const ldap = require('ldapjs');

const client = ldap.createClient({
  url: ['ldap://127.0.0.1:1389', 'ldap://127.0.0.2:1389']
});

client.on('error', (err) => {
  // handle connection error
})

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:

url

This parameter takes a single connection string or an array of connection strings as an input. In case an array is provided, the client tries to connect to the servers in given order. To achieve random server strategy (e.g. to distribute the load among the servers), please shuffle the array before passing it as an argument.

Note On Logger

A passed in logger is expected to conform to the Bunyan API. Specifically, the logger is expected to have a child() method. If a logger is supplied that does not have such a method, then a shim version is added that merely returns the passed in logger.

Known compatible loggers are:

• Bunyan
• Pino

Connection management

As LDAP is a stateful protocol (as opposed to HTTP), having connections torn down from underneath you can be difficult to deal with. Several mechanisms have been provided to mitigate this trouble.

Reconnect

You can provide a Boolean option indicating if a reconnect should be tried. For more sophisticated control, you can provide an Object with the properties initialDelay (default: 100), maxDelay (default: 10000) and failAfter (default: Infinity). After the reconnect you maybe need to bind again.

Client events

The client is an EventEmitter and can emit the following events:

Common patterns

The last two parameters in every API are controls and callback. controls can be either a single instance of a Control or an array of Control objects. You can, and probably will, omit this option.

Almost every operation has the callback form of function(err, res) where err will be an instance of an LDAPError (you can use instanceof to switch). You probably won't need to check the res parameter, but it's there if you do.

bind

bind(dn, password, controls, callback)

Performs a bind operation against the LDAP server.

The bind API only allows LDAP 'simple' binds (equivalent to HTTP Basic Authentication) for now. Note that all client APIs can optionally take an array of Control objects. You probably don't need them though...

Example:

client.bind('cn=root', 'secret', (err) => {
  assert.ifError(err);
});

add

add(dn, entry, controls, callback)

Performs an add operation against the LDAP server.

Allows you to add an entry (which is just a plain JS object), and as always, controls are optional.

Example:

const entry = {
  cn: 'foo',
  sn: 'bar',
  email: ['foo@bar.com', 'foo1@bar.com'],
  objectclass: 'fooPerson'
};
client.add('cn=foo, o=example', entry, (err) => {
  assert.ifError(err);
});

compare

compare(dn, attribute, value, controls, callback)

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

Example:

client.compare('cn=foo, o=example', 'sn', 'bar', (err, matched) => {
  assert.ifError(err);

  console.log('matched: ' + matched);
});

del

del(dn, controls, callback)

Deletes an entry from the LDAP server.

Example:

client.del('cn=foo, o=example', (err) => {
  assert.ifError(err);
});

exop

exop(name, value, controls, callback)

Performs an LDAP extended operation against an LDAP server. name is typically going to be an OID (well, the RFC says it must be; however, ldapjs has no such restriction). value is completely arbitrary, and is whatever the exop says it should be.

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

client.exop('1.3.6.1.4.1.4203.1.11.3', (err, value, res) => {
  assert.ifError(err);

  console.log('whois: ' + value);
});

modify

modify(name, changes, controls, callback)

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.

Example:

const change = new ldap.Change({
  operation: 'add',
  modification: {
    pets: ['cat', 'dog']
  }
});

client.modify('cn=foo, o=example', change, (err) => {
  assert.ifError(err);
});

Change

A Change object maps to the LDAP protocol of a modify change, and requires you to set the operation and modification. The operation is a string, and must be one of:

modification is just a plain old JS object with the values you want.

modifyDN

modifyDN(dn, newDN, controls, callback)

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).

Example:

client.modifyDN('cn=foo, o=example', 'cn=bar', (err) => {
  assert.ifError(err);
});

search

search(base, options, controls, callback)

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. However, ldapjs makes some defaults for you so that if you pass nothing in, it's pretty much equivalent to an HTTP GET operation (i.e., base search against the DN, filter set to always match).

Like every other operation, base is a DN string.

Options can be a string representing a valid LDAP filter or an object containing the following fields:

Responses inside callback of the search method are an EventEmitter where you will get a notification for each searchEntry that comes back from the server. You will additionally be able to listen for a searchRequest , searchReference, error and end event. searchRequest is emitted immediately after every SearchRequest is sent with a SearchRequest parameter. You can do operations like client.abandon with searchRequest.messageID to abandon this search request. Note that the error event will only be for client/TCP errors, not LDAP error codes like the other APIs. You'll want to check the LDAP status code (likely for 0) on the end event to assert success. LDAP search results can give you a lot of status codes, such as time or size exceeded, busy, inappropriate matching, etc., which is why this method doesn't try to wrap up the code matching.

Example:

const opts = {
  filter: '(&(l=Seattle)(email=*@foo.com))',
  scope: 'sub',
  attributes: ['dn', 'sn', 'cn']
};

client.search('o=example', opts, (err, res) => {
  assert.ifError(err);

  res.on('searchRequest', (searchRequest) => {
    console.log('searchRequest: ', searchRequest.messageID);
  });
  res.on('searchEntry', (entry) => {
    console.log('entry: ' + JSON.stringify(entry.object));
  });
  res.on('searchReference', (referral) => {
    console.log('referral: ' + referral.uris.join());
  });
  res.on('error', (err) => {
    console.error('error: ' + err.message);
  });
  res.on('end', (result) => {
    console.log('status: ' + result.status);
  });
});

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." Note that ldapjs doesn't support extensible matching, since it's one of those features that almost nobody actually uses in practice.

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:

(email=foo@bar.com)

ldapjs 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:

(&(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 "example@foo.bar.com".

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:

(&(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.

Paging

Many LDAP server enforce size limits upon the returned result set (commonly 1000). In order to retrieve results beyond this limit, a PagedResultControl is passed between the client and server to iterate through the entire dataset. While callers could choose to do this manually via the controls parameter to search(), ldapjs has internal mechanisms to easily automate the process. The most simple way to use the paging automation is to set the paged option to true when performing a search:

const opts = {
  filter: '(objectclass=commonobject)',
  scope: 'sub',
  paged: true,
  sizeLimit: 200
};
client.search('o=largedir', opts, (err, res) => {
  assert.ifError(err);
  res.on('searchEntry', (entry) => {
    // do per-entry processing
  });
  res.on('page', (result) => {
    console.log('page end');
  });
  res.on('error', (resErr) => {
    assert.ifError(resErr);
  });
  res.on('end', (result) => {
    console.log('done ');
  });
});

This will enable paging with a default page size of 199 (sizeLimit - 1) and will output all of the resulting objects via the searchEntry event. At the end of each result during the operation, a page event will be emitted as well (which includes the intermediate searchResult object).

For those wanting more precise control over the process, an object with several parameters can be provided for the paged option. The pageSize parameter sets the size of result pages requested from the server. If no value is specified, it will fall back to the default (100 or sizeLimit - 1, to obey the RFC). The pagePause parameter allows back-pressure to be exerted on the paged search operation by pausing at the end of each page. When enabled, a callback function is passed as an additional parameter to page events. The client will wait to request the next page until that callback is executed.

Here is an example where both of those parameters are used:

const queue = new MyWorkQueue(someSlowWorkFunction);
const opts = {
  filter: '(objectclass=commonobject)',
  scope: 'sub',
  paged: {
    pageSize: 250,
    pagePause: true
  },
};
client.search('o=largerdir', opts, (err, res) => {
  assert.ifError(err);
  res.on('searchEntry', (entry) => {
    // Submit incoming objects to queue
    queue.push(entry);
  });
  res.on('page', (result, cb) => {
    // Allow the queue to flush before fetching next page
    queue.cbWhenFlushed(cb);
  });
  res.on('error', (resErr) => {
    assert.ifError(resErr);
  });
  res.on('end', (result) => {
    console.log('done');
  });
});

starttls

starttls(options, controls, callback)

Attempt to secure existing LDAP connection via STARTTLS.

Example:

const opts = {
  ca: [fs.readFileSync('mycacert.pem')]
};

client.starttls(opts, (err, res) => {
  assert.ifError(err);

  // Client communication now TLS protected
});

unbind

unbind(callback)

Performs an unbind operation against the LDAP server.

Note that unbind operation is not an opposite operation for bind. Unbinding results in disconnecting the client regardless of whether a bind operation was performed.

The callback argument is optional as unbind does not have a response.

Example:

client.unbind((err) => {
  assert.ifError(err);
});

web ldap manager

ldapjs Client API

Create a client

The code to create a new client looks like:

const ldap = require('ldapjs');

const client = ldap.createClient({
  url: ['ldap://127.0.0.1:1389', 'ldap://127.0.0.2:1389']
});

client.on('error', (err) => {
  // handle connection error
})

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:

url

This parameter takes a single connection string or an array of connection strings as an input. In case an array is provided, the client tries to connect to the servers in given order. To achieve random server strategy (e.g. to distribute the load among the servers), please shuffle the array before passing it as an argument.

Note On Logger

A passed in logger is expected to conform to the Bunyan API. Specifically, the logger is expected to have a child() method. If a logger is supplied that does not have such a method, then a shim version is added that merely returns the passed in logger.

Known compatible loggers are:

• Bunyan
• Pino

Connection management

As LDAP is a stateful protocol (as opposed to HTTP), having connections torn down from underneath you can be difficult to deal with. Several mechanisms have been provided to mitigate this trouble.

Reconnect

You can provide a Boolean option indicating if a reconnect should be tried. For more sophisticated control, you can provide an Object with the properties initialDelay (default: 100), maxDelay (default: 10000) and failAfter (default: Infinity). After the reconnect you maybe need to bind again.

Client events

The client is an EventEmitter and can emit the following events:

Common patterns

The last two parameters in every API are controls and callback. controls can be either a single instance of a Control or an array of Control objects. You can, and probably will, omit this option.

Almost every operation has the callback form of function(err, res) where err will be an instance of an LDAPError (you can use instanceof to switch). You probably won't need to check the res parameter, but it's there if you do.

bind

bind(dn, password, controls, callback)

Performs a bind operation against the LDAP server.

The bind API only allows LDAP 'simple' binds (equivalent to HTTP Basic Authentication) for now. Note that all client APIs can optionally take an array of Control objects. You probably don't need them though...

Example:

client.bind('cn=root', 'secret', (err) => {
  assert.ifError(err);
});

add

add(dn, entry, controls, callback)

Performs an add operation against the LDAP server.

Allows you to add an entry (which is just a plain JS object), and as always, controls are optional.

Example:

const entry = {
  cn: 'foo',
  sn: 'bar',
  email: ['foo@bar.com', 'foo1@bar.com'],
  objectclass: 'fooPerson'
};
client.add('cn=foo, o=example', entry, (err) => {
  assert.ifError(err);
});

compare

compare(dn, attribute, value, controls, callback)

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

Example:

client.compare('cn=foo, o=example', 'sn', 'bar', (err, matched) => {
  assert.ifError(err);

  console.log('matched: ' + matched);
});

del

del(dn, controls, callback)

Deletes an entry from the LDAP server.

Example:

client.del('cn=foo, o=example', (err) => {
  assert.ifError(err);
});

exop

exop(name, value, controls, callback)

Performs an LDAP extended operation against an LDAP server. name is typically going to be an OID (well, the RFC says it must be; however, ldapjs has no such restriction). value is completely arbitrary, and is whatever the exop says it should be.

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

client.exop('1.3.6.1.4.1.4203.1.11.3', (err, value, res) => {
  assert.ifError(err);

  console.log('whois: ' + value);
});

modify

modify(name, changes, controls, callback)

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.

Example:

const change = new ldap.Change({
  operation: 'add',
  modification: {
    pets: ['cat', 'dog']
  }
});

client.modify('cn=foo, o=example', change, (err) => {
  assert.ifError(err);
});

Change

A Change object maps to the LDAP protocol of a modify change, and requires you to set the operation and modification. The operation is a string, and must be one of:

modification is just a plain old JS object with the values you want.

modifyDN

modifyDN(dn, newDN, controls, callback)

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).

Example:

client.modifyDN('cn=foo, o=example', 'cn=bar', (err) => {
  assert.ifError(err);
});

search

search(base, options, controls, callback)

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. However, ldapjs makes some defaults for you so that if you pass nothing in, it's pretty much equivalent to an HTTP GET operation (i.e., base search against the DN, filter set to always match).

Like every other operation, base is a DN string.

Options can be a string representing a valid LDAP filter or an object containing the following fields:

Responses from the search method are an EventEmitter where you will get a notification for each searchEntry that comes back from the server. You will additionally be able to listen for a searchReference, error and end event. Note that the error event will only be for client/TCP errors, not LDAP error codes like the other APIs. You'll want to check the LDAP status code (likely for 0) on the end event to assert success. LDAP search results can give you a lot of status codes, such as time or size exceeded, busy, inappropriate matching, etc., which is why this method doesn't try to wrap up the code matching.

Example:

const opts = {
  filter: '(&(l=Seattle)(email=*@foo.com))',
  scope: 'sub',
  attributes: ['dn', 'sn', 'cn']
};

client.search('o=example', opts, (err, res) => {
  assert.ifError(err);

  res.on('searchEntry', (entry) => {
    console.log('entry: ' + JSON.stringify(entry.object));
  });
  res.on('searchReference', (referral) => {
    console.log('referral: ' + referral.uris.join());
  });
  res.on('error', (err) => {
    console.error('error: ' + err.message);
  });
  res.on('end', (result) => {
    console.log('status: ' + result.status);
  });
});

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." Note that ldapjs doesn't support extensible matching, since it's one of those features that almost nobody actually uses in practice.

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:

(email=foo@bar.com)

ldapjs 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:

(&(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 "example@foo.bar.com".

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:

(&(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.

Paging

Many LDAP server enforce size limits upon the returned result set (commonly 1000). In order to retrieve results beyond this limit, a PagedResultControl is passed between the client and server to iterate through the entire dataset. While callers could choose to do this manually via the controls parameter to search(), ldapjs has internal mechanisms to easily automate the process. The most simple way to use the paging automation is to set the paged option to true when performing a search:

const opts = {
  filter: '(objectclass=commonobject)',
  scope: 'sub',
  paged: true,
  sizeLimit: 200
};
client.search('o=largedir', opts, (err, res) => {
  assert.ifError(err);
  res.on('searchEntry', (entry) => {
    // do per-entry processing
  });
  res.on('page', (result) => {
    console.log('page end');
  });
  res.on('error', (resErr) => {
    assert.ifError(resErr);
  });
  res.on('end', (result) => {
    console.log('done ');
  });
});

This will enable paging with a default page size of 199 (sizeLimit - 1) and will output all of the resulting objects via the searchEntry event. At the end of each result during the operation, a page event will be emitted as well (which includes the intermediate searchResult object).

For those wanting more precise control over the process, an object with several parameters can be provided for the paged option. The pageSize parameter sets the size of result pages requested from the server. If no value is specified, it will fall back to the default (100 or sizeLimit - 1, to obey the RFC). The pagePause parameter allows back-pressure to be exerted on the paged search operation by pausing at the end of each page. When enabled, a callback function is passed as an additional parameter to page events. The client will wait to request the next page until that callback is executed.

Here is an example where both of those parameters are used:

const queue = new MyWorkQueue(someSlowWorkFunction);
const opts = {
  filter: '(objectclass=commonobject)',
  scope: 'sub',
  paged: {
    pageSize: 250,
    pagePause: true
  },
};
client.search('o=largerdir', opts, (err, res) => {
  assert.ifError(err);
  res.on('searchEntry', (entry) => {
    // Submit incoming objects to queue
    queue.push(entry);
  });
  res.on('page', (result, cb) => {
    // Allow the queue to flush before fetching next page
    queue.cbWhenFlushed(cb);
  });
  res.on('error', (resErr) => {
    assert.ifError(resErr);
  });
  res.on('end', (result) => {
    console.log('done');
  });
});

starttls

starttls(options, controls, callback)

Attempt to secure existing LDAP connection via STARTTLS.

Example:

const opts = {
  ca: [fs.readFileSync('mycacert.pem')]
};

client.starttls(opts, (err, res) => {
  assert.ifError(err);

  // Client communication now TLS protected
});

unbind

unbind(callback)

Performs an unbind operation against the LDAP server.

Note that unbind operation is not an opposite operation for bind. Unbinding results in disconnecting the client regardless of whether a bind operation was performed.

The callback argument is optional as unbind does not have a response.

Example:

client.unbind((err) => {
  assert.ifError(err);
});