node-ldapjs/docs/guide.md

title	markdown2extras
LDAP Guide | ldapjs	tables

LDAP Guide

This guide was written assuming that you (1) don't know anything about ldapjs, and perhaps more importantly (2) know little, if anything about LDAP. If you're already an LDAP whiz, please don't read this and feel it's condescending. Most people don't know how LDAP works, other than that "it's that thing that has my password."

By the end of this guide, we'll have a simple LDAP server that accomplishes a "real" task.

What exactly is LDAP?

If you haven't already read the wikipedia entry (which you should go do right now), LDAP is the "Lightweight Directory Access Protocol". A directory service basically breaks down as follows:

• A directory is a tree of entries (similar to but different than an FS).
• Every entry has a unique name in the tree.
• An entry is a set of attributes.
• An attribute is a key/value(s) pairing (multivalue is natural).

It might be helpful to visualize:

              o=example
              /       \
         ou=users     ou=groups
        /      |         |     \
    cn=john  cn=jane    cn=dudes  cn=dudettes
    /
keyid=foo

Let's say we wanted to look at the record cn=john:

dn: cn=john, ou=users, o=example
cn: john
sn: smith
email: john@example.com
email: john.smith@example.com
objectClass: person

A few things to note:

• All names in a directory tree are actually referred to as a distinguished name, or dn for short. A dn is comprised of attributes that lead to that node in the tree, as shown above (the syntax is foo=bar, ...).
• The root of the tree is at the right of the dn, which is inverted from a filesystem hierarchy.
• Every entry in the tree is an instance of an objectclass.
• An objectclass is a schema concept; think of it like a table in a traditional ORM.
• An objectclass defines what attributes an entry can have (on the ORM analogy, an attribute would be like a column).

That's it. LDAP, then, is the protocol for interacting with the directory tree, and it's comprehensively specified for common operations, like add/update/delete and importantly, search. Really, the power of LDAP comes through the search operations defined in the protocol, which are richer than HTTP query string filtering, but less powerful than full SQL. You can think of LDAP as a NoSQL/document store with a well-defined query syntax.

So, why isn't LDAP more popular for a lot of applications? Like anything else that has "simple" or "lightweight" in the name, it's not really that lightweight. In particular, almost all of the implementations of LDAP stem from the original University of Michigan codebase written in 1996. At that time, the original intention of LDAP was to be an IP-accessible gateway to the much more complex X.500 directories, which means that a lot of that baggage has carried through to today. That makes for a high barrier to entry, when most applications just don't need most of those features.

How is ldapjs any different?

Well, on the one hand, since ldapjs has to be 100% wire compatible with LDAP to be useful, it's not. On the other hand, there are no forced assumptions about what you need and don't need for your use of a directory system. For example, want to run with no-schema in OpenLDAP/389DS/et al? Good luck. Most of the server implementations support arbitrary "backends" for persistence, but really you'll be using BDB.

Want to run schema-less in ldapjs, or wire it up with some mongoose models? No problem. Want to back it to redis? Should be able to get some basics up in a day or two.

Basically, the ldapjs philospohy is to deal with the "muck" of LDAP, and then get out of the way so you can just use the "good parts."

Ok, cool. Learn me some LDAP!

With the initial fluff out of the way, let's do something crazy to teach you some LDAP. Let's put an LDAP server up over the top of your (Linux) host's /etc/passwd and /etc/group files. Usually sysadmins "go the other way," and replace /etc/passwd with a PAM module to LDAP. While this is probably not a super useful real-world use case, it will teach you some of the basics. If it is useful to you, then that's gravy.

Install

If you don't already have node.js and npm, clearly you need those, so follow the steps at nodejs.org and npmjs.org, respectively. After that, run:

$ npm install ldapjs

Rather than overload you with client-side programming for now, we'll use the OpenLDAP CLI to interact with our server. It's almost certainly already installed on your system, but if not, you can get it from brew/apt/yum/your package manager here.

To get started, open some file, and let's get the library loaded and a server created:

var ldap = require('ldapjs');

var server = ldap.createServer();

server.listen(1389, function() {
  console.log('/etc/passwd LDAP server up at: %s', server.url);
});

And run that. Doing anything will give you errors (LDAP "No Such Object") since we haven't added any support in yet, but go ahead and try it anyway:

$ ldapsearch -H ldap://localhost:1389 -x -b "o=myhost" objectclass=*

Before we go any further, note that the complete code for the server we are about to build up is on the examples page.

Bind

So, lesson #1 about LDAP: unlike HTTP, it's connection-oriented; that means that you authenticate (in LDAP nomenclature this is called a bind), and all subsequent operations operate at the level of priviledge you established during a bind. You can bind any number of times on a single connection and change that identity. Technically, it's optional, and you can support anonymous operations from clients, but (1) you probably don't want that, and (2) most LDAP clients will initiate a bind anyway (OpenLDAP will), so let's add it in and get it out of our way.

What we're going to do is add a "root" user to our LDAP server. This root user has no correspondence to our Unix root user, it's just something we're making up and going to use for allowing an (LDAP) admin to do anything. To do so, add this code into your file:

server.bind('cn=root', function(req, res, next) {
  if (req.dn.toString() !== 'cn=root' || req.credentials !== 'secret')
    return next(new ldap.InvalidCredentialsError());

  res.end();
  return next();
});

Not very secure, but this is a demo. What we did there was "mount" a tree in the ldapjs server, and add a handler for the bind method. If you've ever used express, this pattern should be really familiar; you can add any number of handlers in, as we'll see later.

On to the meat of the method. What's up with this?

if (req.dn.toString() !== 'cn=root' || req.credentials !== 'secret')

The first part req.dn.toString() !== 'cn=root': you're probably thinking "WTF?!? Does ldapjs allow something other than cn=root into this handler?" Sort of. It allows cn=root and any children into that handler. So the entries cn=root and cn=evil, cn=root would both match and flow into this handler. Hence that check. The second check req.credentials is probably obvious, but it brings up an important point, and that is the req, res objects in ldapjs are not homogenous across server operation types. Unlike HTTP, there's not a single message format, so each of the operations has fields and functions appropriate to that type. The LDAP bind operation has credentials, which are a string representation of the client's password. This is logically the same as HTTP Basic Authentication (there are other mechanisms, but that's out of scope for a getting started guide). Ok, if either of those checks failed, we pass a new ldapjs Error back into the server, and it will (1) halt the chain, and (2) send the proper error code back to the client.

Lastly, assuming that this request was ok, we just end the operation with res.end(). The return next() isn't strictly necessary, since here we only have one handler in the chain, but it's good habit to always do that, so if you add another handler in later you won't get bit by it not being invoked.

Blah blah, let's try running the ldap client again, first with a bad password:

$ ldapsearch -H ldap://localhost:1389 -x -D cn=root -w foo -b "o=myhost" objectclass=*

ldap_bind: Invalid credentials (49)
    matched DN: cn=root
    additional info: Invalid Credentials

And again with the correct one:

$ ldapsearch -H ldap://localhost:1389 -x -D cn=root -w secret -LLL -b "o=myhost" objectclass=*

No such object (32)
Additional information: No tree found for: o=myhost

Don't worry about all the flags we're passing into OpenLDAP, that's just to make their CLI less annonyingly noisy. This time, we got another No such object error, but it's for the tree o=myhost. That means our bind went through, and our search failed, since we haven't yet added a search handler. Just one more small thing to do first.

Remember earlier I said there were no authorization rules baked into LDAP? Well, we added a bind route, so the only user that can authenticate is cn=root, but what if the remote end doesn't authenticate at all? Right, nothing says they have to bind, that's just what the common clients do. Let's add a quick authorization handler that we'll use in all our subsequent routes:

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

  return next();
}

Should be pretty self-explanatory, but as a reminder, LDAP is connection oriented, so we check that the connection remote user was indeed our cn=root (by default ldapjs will have a DN of cn=anonymous if the client didn't bind).

Search

We said we wanted to allow LDAP operations over /etc/passwd, so let's detour for a moment to explain an /etc/passwd record.

jsmith:x:1001:1000:Joe Smith,Room 1007,(234)555-8910,(234)555-0044,email:/home/jsmith:/bin/sh

The sample record above maps to:

Field	Description
jsmith	Username
x	Placeholder for password hash
1001	Numeric UID
1000	Numeric Primary GID
'Joe Smith,...'	DisplayName
/home/jsmith	Home directory
/bin/sh	Shell

Let's write some handlers to parse that and transform it into an LDAP search record (note, you'll need to add var fs = require('fs'); at the top of the source file).

First, make a handler that just loads the "user database" in a "pre" handler:

function loadPasswdFile(req, res, next) {
  fs.readFile('/etc/passwd', 'utf8', function(err, data) {
    if (err)
      return next(new ldap.OperationsError(err.message));

    req.users = {};

    var lines = data.split('\n');
    for (var i = 0; i < lines.length; i++) {
      if (!lines[i] || /^#/.test(lines[i]))
        continue;

      var record = lines[i].split(':');
      if (!record || !record.length)
        continue;

      req.users[record[0]] = {
        dn: 'cn=' + record[0] + ', ou=users, o=myhost',
        attributes: {
          cn: record[0],
          uid: record[2],
          gid: record[3],
          description: record[4],
          homedirectory: record[5],
          shell: record[6] || '',
          objectclass: 'unixUser'
        }
      };
    }

    return next();
  });
}

Ok, all that did is tack the /etc/passwd records onto req.users so that any subsequent handler doesn't have to reload the file. Next, let's write a search handler to process that:

var pre = [authorize, loadPasswdFile];

server.search('o=myhost', pre, function(req, res, next) {
  Object.keys(req.users).forEach(function(k) {
    if (req.filter.matches(req.users[k].attributes))
      res.send(req.users[k]);
  });

  res.end();
  return next();
});

And try running:

$ ldapsearch -H ldap://localhost:1389 -x -D cn=root -w secret -LLL -b "o=myhost" cn=root
dn: cn=root, ou=users, o=myhost
cn: root
uid: 0
gid: 0
description: System Administrator
homedirectory: /var/root
shell: /bin/sh
objectclass: unixUser

Sweet! Try this out too:

$ ldapsearch -H ldap://localhost:1389 -x -D cn=root -w secret -LLL -b "o=myhost" objectclass=*
...

You should have seen an entry for every record in /etc/passwd with the second. What all did we do here? A lot. Let's break this down...

What did I just do on the command line?

Let's start with looking at what you even asked for:

$ ldapsearch -H ldap://localhost:1389 -x -D cn=root -w secret -LLL -b "o=myhost" cn=root

We can throw away ldapsearch -H -x -D -w -LLL, as those just specify the URL to connect to, the bind credentials and the -LLL just quiets down OpenLDAP. That leaves us with: -b "o=myhost" cn=root.

The -b o=myhost tells our LDAP server where to start looking in the tree for entries that might match the search filter, which above is cn=root.

In this little LDAP example, we're mostly throwing out any qualification of the "tree," since there's not actually a tree in /etc/passwd (we will extend later with /etc/group). Remember how I said ldapjs gets out of the way and doesn't force anything on you? Here's an example. If we wanted an LDAP server to run over the filesystem, we actually would use this, but here, meh.

Next, cn=root is the search "filter". LDAP has a rich specification of filters, where you can specify and, or, not, >=, <=, equal, wildcard, present and a few other esoteric things. Really, equal, wildcard, present and the boolean operators are all you'll likely ever need. So, the filter cn=root is an "equality" filter, and says to only return entries that have attributes that match that. In the second invocation, we used a 'presence' filter, to say 'return any entries that have an objectclass' attribute, which in LDAP parlance is saying "give me everything."

The code

In the code above, let's ignore the fs and split stuff, since really all we did was read in /etc/passwd line by line. After that, we looked at each record and made the cheesiest transform ever, which is making up a "search entry." A search entry must have a DN so the client knows what record it is, and a set of attributes. So that's why we did this:

var entry = {
  dn: 'cn=' + record[0] + ', ou=users, o=myhost',
  attributes: {
    cn: record[0],
    uid: record[2],
    gid: record[3],
    description: record[4],
    homedirectory: record[5],
    shell: record[6] || '',
    objectclass: 'unixUser'
  }
};

Next, we let ldapjs do all the hard work of figuring out LDAP search filters for us by calling req.filter.matches. If it matched, we return the whole record with res.send. In this little example we're running O(n), so for something big and/or slow, you'd have to do some work to effectively write a query planner (or just not support it...). For some reference code, check out node-ldapjs-riak, which takes on the fairly difficult task of writing a 'full' LDAP server over riak.

To demonstrate what ldapjs is doing for you, let's find all users who have a shell set to /bin/false and whose name starts with p (I'm doing this on Ubuntu). Then, let's say we only care about their login name and primary group id. We'd do this:

$ ldapsearch -H ldap://localhost:1389 -x -D cn=root -w secret -LLL -b "o=myhost" "(&(shell=/bin/false)(cn=p*))" cn gid
dn: cn=proxy, ou=users, o=myhost
cn: proxy
gid: 13

dn: cn=pulse, ou=users, o=myhost
cn: pulse
gid: 114

Add

This is going to be a little bit ghetto, since what we're going to do is just use node's child process module to spawn calls to adduser. Go ahead and add the following code in as another handler (you'll need a var spawn = require('child_process').spawn; at the top of your file):

server.add('ou=users, o=myhost', pre, function(req, res, next) {
  if (!req.dn.rdns[0].cn)
    return next(new ldap.ConstraintViolationError('cn required'));

  if (req.users[req.dn.rdns[0].cn])
    return next(new ldap.EntryAlreadyExistsError(req.dn.toString()));

  var entry = req.toObject().attributes;

  if (entry.objectclass.indexOf('unixUser') === -1)
    return next(new ldap.ConstraintViolationError('entry must be a unixUser'));

  var opts = ['-m'];
  if (entry.description) {
    opts.push('-c');
    opts.push(entry.description[0]);
  }
  if (entry.homedirectory) {
    opts.push('-d');
    opts.push(entry.homedirectory[0]);
  }
  if (entry.gid) {
    opts.push('-g');
    opts.push(entry.gid[0]);
  }
  if (entry.shell) {
    opts.push('-s');
    opts.push(entry.shell[0]);
  }
  if (entry.uid) {
    opts.push('-u');
    opts.push(entry.uid[0]);
  }
  opts.push(entry.cn[0]);
  var useradd = spawn('useradd', opts);

  var messages = [];

  useradd.stdout.on('data', function(data) {
    messages.push(data.toString());
  });
  useradd.stderr.on('data', function(data) {
    messages.push(data.toString());
  });

  useradd.on('exit', function(code) {
    if (code !== 0) {
      var msg = '' + code;
      if (messages.length)
        msg += ': ' + messages.join();
      return next(new ldap.OperationsError(msg));
    }

    res.end();
    return next();
  });
});

Then, you'll need to be root to have this running, so start your server with sudo (or be root, whatever). Now, go ahead and create a file called user.ldif with the following contents:

dn: cn=ldapjs, ou=users, o=myhost
objectClass: unixUser
cn: ldapjs
shell: /bin/bash
description: Created via ldapadd

Now go ahead and invoke with:

$ ldapadd -H ldap://localhost:1389 -x -D cn=root -w secret -f ./user.ldif
adding new entry "cn=ldapjs, ou=users, o=myhost"

Let's confirm he got added with an ldapsearch:

$ ldapsearch -H ldap://localhost:1389 -LLL -x -D cn=root -w secret -b "ou=users, o=myhost" cn=ldapjs
dn: cn=ldapjs, ou=users, o=myhost
cn: ldapjs
uid: 1001
gid: 1001
description: Created via ldapadd
homedirectory: /home/ldapjs
shell: /bin/bash
objectclass: unixUser

As before, here's a breakdown of the code:

server.add('ou=users, o=myhost', pre, function(req, res, next) {
  if (!req.dn.rdns[0].cn)
    return next(new ldap.ConstraintViolationError('cn required'));

  if (req.users[req.dn.rdns[0].cn])
    return next(new ldap.EntryAlreadyExistsError(req.dn.toString()));

  var entry = req.toObject().attributes;

  if (entry.objectclass.indexOf('unixUser') === -1)
    return next(new ldap.ConstraintViolationError('entry must be a unixUser'));

A few new things:

• We mounted this handler at ou=users, o=myhost. Why? What if we want to extend this little project with groups? We probably want those under a different part of the tree.
• We did some really minimal schema enforcement by:
  • Checking that the leaf RDN (relative distinguished name) was a cn attribute.
  • We then did req.toObject(). As mentioned before, each of the req/res objects have special APIs that make sense for that operation. Without getting into the details, the LDAP add operation on the wire doesn't look like a JS object, and we want to support both the LDAP nerd that wants to see what got sent, and the "easy" case. So use .toObject(). Note we also filtered out to the attributes portion of the object since that's all we're really looking at.
  • Lastly, we did a super minimal check to see if the entry was of type unixUser. Frankly for this case, it's kind of useless, but it does illustrate one point: attribute names are case-insensitive, so ldapjs converts them all to lower case (note the client sent objectClass over the wire).

After that, we really just delegated off to the useradd command. As far as I know, there is not a node.js module that wraps up getpwent and friends, otherwise we'd use that.

Now, what's missing? Oh, right, we need to let you set a password. Well, let's support that via the modify command.

Modify

Unlike HTTP, "partial" document updates are fully specified as part of the RFC, so appending, removing, or replacing a single attribute is pretty natural. Go ahead and add the following code into your source file:

server.modify('ou=users, o=myhost', pre, function(req, res, next) {
  if (!req.dn.rdns[0].cn || !req.users[req.dn.rdns[0].cn])
    return next(new ldap.NoSuchObjectError(req.dn.toString()));

  if (!req.changes.length)
    return next(new ldap.ProtocolError('changes required'));

  var user = req.users[req.dn.rdns[0].cn].attributes;
  var mod;

  for (var i = 0; i < req.changes.length; i++) {
    mod = req.changes[i].modification;
    switch (req.changes[i].operation) {
    case 'replace':
      if (mod.type !== 'userpassword' || !mod.vals || !mod.vals.length)
        return next(new ldap.UnwillingToPerformError('only password updates ' +
                                                     'allowed'));
      break;
    case 'add':
    case 'delete':
      return next(new ldap.UnwillingToPerformError('only replace allowed'));
    }
  }

  var passwd = spawn('chpasswd', ['-c', 'MD5']);
  passwd.stdin.end(user.cn + ':' + mod.vals[0], 'utf8');

  passwd.on('exit', function(code) {
    if (code !== 0)
      return next(new ldap.OperationsError(code));

    res.end();
    return next();
  });
});

Basically, we made sure the remote client was targeting an entry that exists, ensuring that they were asking to "replace" the userPassword attribute (which is the 'standard' LDAP attribute for passwords; if you think it's easier to use 'password', knock yourself out), and then just delegating to the chpasswd command (which lets you change a user's password over stdin). Next, go ahead and create a passwd.ldif file:

dn: cn=ldapjs, ou=users, o=myhost
changetype: modify
replace: userPassword
userPassword: secret
-

And then run the OpenLDAP CLI:

$ ldapmodify -H ldap://localhost:1389 -x -D cn=root -w secret -f ./passwd.ldif

You should now be able to login to your box as the ldapjs user. Let's get the last "mainline" piece of work out of the way, and delete the user.

Delete

Delete is pretty straightforward. The client gives you a dn to delete, and you delete it :). Add the following code into your server:

server.del('ou=users, o=myhost', pre, function(req, res, next) {
  if (!req.dn.rdns[0].cn || !req.users[req.dn.rdns[0].cn])
    return next(new ldap.NoSuchObjectError(req.dn.toString()));

  var userdel = spawn('userdel', ['-f', req.dn.rdns[0].cn]);

  var messages = [];
  userdel.stdout.on('data', function(data) {
    messages.push(data.toString());
  });
  userdel.stderr.on('data', function(data) {
    messages.push(data.toString());
  });

  userdel.on('exit', function(code) {
    if (code !== 0) {
      var msg = '' + code;
      if (messages.length)
        msg += ': ' + messages.join();
      return next(new ldap.OperationsError(msg));
    }

    res.end();
    return next();
  });
});

And then run the following command:

$ ldapdelete -H ldap://localhost:1389 -x -D cn=root -w secret "cn=ldapjs, ou=users, o=myhost"

Where to go from here

The complete source code for this example server is available in examples. Make sure to read up on the server and client APIs. If you're looking for a "drop in" solution, take a look at ldapjs-riak.

Mozilla still maintains some web pages with LDAP overviews if you look around, if you're looking for more tutorials. After that, you'll need to work your way through the RFCs as you work through the APIs in ldapjs.