node-ldapjs/docs/client.md

---
title: ldapjs
brand: spartan
markdown2extras: wiki-tables
logo-color: green
logo-font-family: google:Aldrich, Verdana, sans-serif
header-font-family: google:Aldrich, Verdana, sans-serif
---

# Overview

This documents the ldapjs client API; this assumes that you are familiar with
LDAP, so if you're not, hit the [guide](http://ldapjs.org/guide.html) first.

# Create a client

The code to create a new client looks like:

    var client = ldap.createClient({
      url: 'ldap://127.0.0.1:1389'
    });

You can use `ldap://` or `ldaps://`; the latter would connect over SSL (note
this will not use the LDAP TLS extended operation, but literally an SSL
connection to port 636, as in LDAP v2). Full list of options:

||url|| a valid LDAP url||
||socketPath|| If you're running an LDAP server over a Unix Domain Socket, use this||
||log4js|| You can optionally pass in a log4js instance that the client will get a logger from.  You'll need to set the level to `TRACE` To get any output from the client||
||numConnections||The size of the connection pool. Default is 1||

## Connection management

If you'll recall, the LDAP protocol is connection-oriented, and completely
asynchronous on a connection (meaning you can send as many requests as you want
without waiting for responses).  However, our friend `bind` is a little
different in that you generally want to wait for binds to be completed since
subsequent operations assume that level of priviledge.

The ldapjs client deals with this by maintaing a connection pool, and splaying
requests across that connection pool, with the exception of `bind` and `unbind`,
which it will apply to all connections in the pool.  By default a client will
have one connection in the pool (since it's async already, you don't always need
the complexity of a pool).  And after that, the operations in the client are
pretty much a mapping of the LDAP C API, but made higher-level, so they make
sense in JS.

## 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`. 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 ldapjs Error (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)`

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

If you have > 1 connection in the connection pool, you'll be called back after
*all* of the connections are bound, not just the first one.

Example:

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

# add
`add(dn, entry, controls, callback)`

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

Example:

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

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

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

Example:

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

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

# del
`del(dn, controls, callbak)`


Deletes an entry from the LDAP server.

Example:

    client.del('cn=foo, o=example', function(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. 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', function(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 you can pass
in a single `Change` or an array of `Change`.

Example:

    var change = new Change({
      type: 'add',
      modification: {
        pets: ['cat', 'dog']
      }
    });

    client.modify('cn=foo, o=example', change, function(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:

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

`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 automagically 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', function(err) {
      assert.ifError(err);
    });

# search
`search(base, options, controls, callback)`

The search operation is more complex than the 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 has the following
fields:

||scope||One of `base`, `one`, or `sub`. Defaults to `base`||
||filter||A string version of an LDAP filter (see below), or a programatically constructed `Filter` object. Defaults to `(objectclass=*)`||
||attributes||attributes to select and return (if these are set, the server will return *only* these attributes). Defaults to the empty set, which means all attributes||
||attrsOnly||boolean on whether you want the server to only return the names of the attributes, and not their values.  Borderline useless.  Defaults to false||
||sizeLimit||the maximum number of entries to return. Defaults to 0 (unlimited)||
||timeLimit||the maximum amount of time the server should take in responding, in seconds. Defaults to 10.  Lots of servers will ignore this||

Responses from the `search` method are an `EventEmitter` where you will get a
notification for each search entry that comes back from the server.  You will
additionally be able to listen for an `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., etc.,
which is why this method doesn't try to wrap up the code matching.

Example:

    var opts = {
      filter: '(&(l=Seattle)(email=*@foo.com))',
      scope: 'sub'
    };

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

      res.on('searchEntry', function(entry) {
        console.log('entry: ' + JSON.stringify(entry.object));
      });
      res.on('error', function(err) {
        console.error('error: ' + err.message);
      });
      res.on('end', function(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 "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)

Note that ldapjs requires all filters to be surrounded by '()' blocks. Ok, that
was easy.  Let's now assume 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))

Ok, so now our filter is actually three LDAP filters.  We have an `and` filter,
an `equality` filter (the l=Seattle), and a `substring` filter.  Substrings are
wildcard filters.  Now, let's say we want to also set our filter to include a
specification that either the employeeType *not* be a manager or a secretary:

    (&(email=*@bar.com)(l=Seattle)(!(|(employeeType=manager)(employeeType=secretary))))

It gets a little bit complicated, but it's actually quite powerful, and lets you
find almost anything you're looking for.

# unbind
`unbind(callback)`

The unbind operation takes no parameters other than a callback, and will unbind
(and disconnect) *all* of the connections in the pool.

Example:

    client.unbind(function(err) {
      assert.ifError(err);
    });