ActiveDirectory for Node

ActiveDirectory is an ldapjs client for authN (authentication) and authZ (authorization) for Microsoft Active Directory with range retrieval support for large Active Directory installations. This code was a port of an existing C# library (not published) that I had written a few years ago. Here are the key features

• Authenticate
• Authorization (via group membership information)
• Nested groups support
• Range specifier / retrieval support (http://msdn.microsoft.com/en-us/library/dd358433.aspx)
• Automatic paging support (Active Directory results (MaxPageSize) limited to 1000 per request by default)
• Recycle bin (tombstone) query support
• Referral support

Required Libraries

ActiveDirectory uses the following additional node modules:

• underscore - a utility-belt library for JavaScript that provides a lot of the functional programming support
• async - Async utilities for node and the browser
• ldapjs - A pure JavaScript, from-scratch framework for implementing LDAP clients and servers in Node.js
• bunyan - A simple and fast JSON logging module for node.js services

Installation

npm install activedirectory

Usage

var ActiveDirectory = require('activedirectory');
var config = { url: 'ldap://dc.domain.com',
               baseDN: 'dc=domain,dc=com',
               username: 'username@domain.com',
               password: 'password' }
var ad = new ActiveDirectory(config);

The username and password specified in the configuration are what are used for user and group lookup operations.

Documentation

• authenticate
• isUserMemberOf
• find
• findUser
• findGroup
• findUsers
• findGroups
• groupExists
• userExists
• getGroupMembershipForGroup
• getGroupMembershipForUser
• getUsersForGroup
• getRootDSE
• findDeletedObjects

var ad = new ActiveDirectory(config);
var username = 'john.smith@domain.com';
var password = 'password';

ad.authenticate(username, password, function(err, auth) {
  if (err) {
    console.log('ERROR: '+JSON.stringify(err));
    return;
  }
  
  if (auth) {
    console.log('Authenticated!');
  }
  else {
    console.log('Authentication failed!');
  }
});

• opts - Optional parameters to extend or override functionality. See optional parameters.
• username - The username to check for membership. Can be specied as a sAMAccountName, userPrincipalName or distinguishedName (dn)
• groupName - The group to check for membership. Can be a commonName (cn) or a distinguishedName (dn)
• callback - The callback to execute when completed. callback(err: {Object}, result: {Boolean})

Example

var username = 'user@domain.com';
var groupName = 'Employees';

var ad = new ActiveDirectory(config);
var ad.isUserMemberOf(username, groupName, function(err, isMember) {
  if (err) {
    console.log('ERROR: ' +JSON.stringify(err));
    return;
  }

  console.log(username + ' isMemberOf ' + groupName + ': ' + isMember);
});

• opts - Optional parameters to extend or override functionality. See optional parameters.
• groupName - The group to check if is defined. Can be a commonName (cn) or a distinguishedName (dn)
• callback - The callback to execute when completed. callback(err: {Object}, result: {Boolean})

Example

var groupName = 'Employees';

var ad = new ActiveDirectory(config);
ad.groupExists(groupName, function(err, exists) {
  if (err) {
    console.log('ERROR: ' +JSON.stringify(err));
    return;
  }

  console.log(groupName + ' exists: ' + exists);
});

• opts - Optional parameters to extend or override functionality. See optional parameters.
• username - The username to check if it exists. Can be a sAMAccountName, userPrincipalName or a distinguishedName (dn)
• callback - The callback to execute when completed. callback(err: {Object}, result: {Boolean})

Example

var username = 'john.smith@domain.com';

var ad = new ActiveDirectory(config);
ad.userExists(username, function(err, exists) {
  if (err) {
    console.log('ERROR: ' +JSON.stringify(err));
    return;
  }

  console.log(username + ' exists: ' + exists);
});

• opts - Optional parameters to extend or override functionality. See optional parameters.
• groupName - The name of the group to retrieve membership from. Can be a commonName (cn) or a distinguishedName (dn)
• callback - The callback to execute when completed. callback(err: {Object}, groups: {Array[User]})

Example

var groupName = 'Employees';

var ad = new ActiveDirectory(config);
ad.getUsersForGroup(groupName, function(err, users) {
  if (err) {
    console.log('ERROR: ' +JSON.stringify(err));
    return;
  }

  if (! users) console.log('Group: ' + groupName + ' not found.');
  else {
    console.log(JSON.stringify(users));
  }
});

• opts - Optional parameters to extend or override functionality. See optional parameters.
• username - The name of the user to retrieve group membership for. Can be a sAMAccountName, userPrincipalName, or a distinguishedName (dn)
• callback - The callback to execute when completed. callback(err: {Object}, groups: {Array[Group]})

Example

var sAMAccountName = 'john.smith@domain.com';

var ad = new ActiveDirectory(config);
ad.getGroupMembershipForUser(sAMAccountName, function(err, groups) {
  if (err) {
    console.log('ERROR: ' +JSON.stringify(err));
    return;
  }

  if (! groups) console.log('User: ' + sAMAccountName + ' not found.');
  else console.log(JSON.stringify(groups));
});

• opts - Optional parameters to extend or override functionality. See optional parameters.
• groupName - The name of the user to retrieve group membership for. Can be a sAMAccountName, userPrincipalName, or a distinguishedName (dn)
• callback - The callback to execute when completed. callback(err: {Object}, groups: {Array[Group]})

Example

var groupName = 'Employees';

var ad = new ActiveDirectory(config);
ad.getGroupMembershipForGroup(groupName, function(err, groups) {
  if (err) {
    console.log('ERROR: ' +JSON.stringify(err));
    return;
  }

  if (! groups) console.log('Group: ' + groupName + ' not found.');
  else console.log(JSON.stringify(groups));
});

• opts - Optional parameters to extend or override functionality. See optional parameters. If only a string is provided, then the string is assumed to be an LDAP filter
• callback - The callback to execute when completed. callback(err: {Object}, groups: {Array[Group]})

Example

var _ = require('underscore');
var query = 'cn=*Exchange*';
var opts = {
  includeMembership : [ 'group', 'user' ], // Optionally can use 'all'
  includeDeleted : false
};

var ad = new ActiveDirectory(config);
ad.find(query, function(err, results) {
  if ((err) || (! results)) {
    console.log('ERROR: ' + JSON.stringify(err));
    return;
  }

  console.log('Groups');
  _.each(results.groups, function(group) {
    console.log('  ' + group.cn);
  });

  console.log('Users');
  _.each(results.users, function(user) {
    console.log('  ' + user.cn);
  });

  console.log('Other');
  _.each(results.other, function(other) {
    console.log('  ' + other.cn);
  });
});

• Enable the Active Directory Recycle Bin (and other New Features)
• Reanimating Active Directory Tombstone Objects

Note: That when an LDAP entry / object is tombstoned, not all attributes for that item are retained. This is a limitation of Active Directory itself and not the library itself.

Arguments

• opts - Optional parameters to extend or override functionality. See optional parameters. If only a string is provided, then the string is assumed to be an LDAP filter
• callback - The callback to execute when completed. callback(err: {Object}, result: {Array})

If the baseDN is not specified, then a RootDSE query will be performed on the attached URL and 'ou-Deleted Objects' will be appended.

Example

var url = 'ldap://yourdomain.com';
var opts = {
  baseDN: 'ou=Deleted Objects, dc=yourdomain, dc=com',
  filter: 'cn=*Bob*'
};
ad.findDeletedObjects(opts, function(err, result) {
  if (err) {
    console.log('ERROR: ' +JSON.stringify(err));
    return;
  }

  console.log('findDeletedObjects: '+JSON.stringify(result));
});

• opts - Optional parameters to extend or override functionality. See optional parameters.
• username - The username to retrieve information about. Optionally can pass in the distinguishedName (dn) of the user to retrieve.
• callback(err, user) - The callback to execute when completed. callback(err: {Object}, user: {User})

Example

// Any of the following username types can be searched on
var sAMAccountName = 'username';
var userPrincipalName = 'username@domain.com';
var dn = 'CN=Smith\\, John,OU=Users,DC=domain,DC=com';

// Find user by a sAMAccountName
var ad = new ActiveDirectory(config);
ad.findUser(sAMAccountName, function(err, user) {
  if (err) {
    console.log('ERROR: ' +JSON.stringify(err));
    return;
  }

  if (! user) console.log('User: ' + sAMAccountName + ' not found.');
  else console.log(JSON.stringify(user));
});

• opts - Optional parameters to extend or override functionality. See optional parameters. If only a string is provided, then the string is assumed to be an LDAP filter that will be appended as the last parameter in the default LDAP filter.
• callback - The callback to execute when completed. callback(err: {Object}, users: {Array[User]})

Example

var query = 'cn=*George*';

var ad = new ActiveDirectory(config);
ad.findUsers(query, true, function(err, users) {
  if (err) {
    console.log('ERROR: ' +JSON.stringify(err));
    return;
  }

  if ((! users) || (users.length == 0)) console.log('No users found.');
  else {
    console.log('findUsers: '+JSON.stringify(users));
  }
});

• opts - Optional parameters to extend or override functionality. See optional parameters.
• groupName - The group (cn) to retrieve information about. Optionally can pass in the distinguishedName (dn) of the group to retrieve.
• callback(err, group) - The callback to execute when completed. callback(err: {Object}, group: {Group})

Example

// Any of the following group names can be searched on
var groupName = 'Employees';
var dn = 'CN=Employees,OU=Groups,DC=domain,DC=com'

// Find group by common name
var ad = new ActiveDirectory(config);
ad.findGroup(groupName, function(err, group) {
  if (err) {
    console.log('ERROR: ' +JSON.stringify(err));
    return;
  }

  if (! user) console.log('Group: ' + groupName + ' not found.');
  else {
    console.log(group);
    console.log('Members: ' + (group.member || []).length);
  }
});

• opts - Optional parameters to extend or override functionality. See optional parameters. If only a string is provided, then the string is assumed to be an LDAP filter that will be appended as the last parameter in the default LDAP filter.
• callback - The callback to execute when completed. callback(err: {Object}, groups: {Array[Group]})

Example

var query = 'CN=*Admin*';

var ad = new ActiveDirectory(config);
ad.findGroups(query, function(err, groups) {
  if (err) {
    console.log('ERROR: ' +JSON.stringify(err));
    return;
  }

  if ((! groups) || (groups.length == 0)) console.log('No groups found.');
  else {
    console.log('findGroups: '+JSON.stringify(groups));
  }
});

var url = 'ldap://yourdomain.com';
ActiveDirectory.prototype.getRootDSE(url, [ 'defaultNamingContext' ], function(err, result) {
  if (err) {
    console.log('ERROR: ' +JSON.stringify(err));
    return;
  }

  console.log('getRootDSE: '+JSON.stringify(result));
});

// Or can be called with an instance...
var ad = new ActiveDirectory(config);
ad.getRootDSE(function(err, result) {
  //...
});

var ad = new ActiveDirectory({ url: 'ldap://dc.domain.com',
                               baseDN: 'dc=domain,dc=com',
                               username: 'username@domain.com',
                               password: 'password',
                               attributes: {
                                 user: [ 'myCustomAttribute', 'mail', 'userPrinicipalName' ],
                                 group: [ 'anotherCustomAttribute', 'objectCategory' ]
                               }
                              });

{
  referrals: {
    enabled: false,
    excluded: [
      'ldaps?://ForestDnsZones\./.*',
      'ldaps?://DomainDnsZones\./.*',
      'ldaps?://.*/CN=Configuration,.*'
    ]
  }
}

var ad = new ActiveDirectory({ url: 'ldap://dc.domain.com',
                               baseDN: 'dc=domain,dc=com',
                               username: 'username@domain.com',
                               password: 'password',
                               attributes: { ... },
                               referrals: {
                                 enabled: true,
                                 excluded: [ ]
                               }
                              });

function customEntryParser(entry, raw, callback){
    if (raw.hasOwnProperty("objectSid")){
        entry.objectSid = raw.objectSid;
    }
    if (raw.hasOwnProperty("objectGUID")){
        entry.objectGUID = raw.objectGUID;
    }
    callback(entry);
};

var ad = new ActiveDirectory({ url: 'ldap://dc.domain.com',
                               baseDN: 'dc=domain,dc=com',
                               username: 'username@domain.com',
                               password: 'password',
                               attributes: { ... },
                               referrals: { ... },
                               entryParser : customEntryParser
                              });

Optionally, you can specify your custom entry parser as part of the 'opts' object. See optional parameters for more information.

var opts = function(entry, raw, callback) {
  entry.retrievedAt = new Date();
  callback(entry);
};
ad.findUser(opts, 'userPrincipalName=bob@domain.com', function(err, user) {
 ...
});

• baseDN - The alternative baseDN to use than the one specified in the ctor.
• includeMembership - Indicates that a search or find operation should enumerate the group memberships of the specified result types. Supported values are [ 'user', 'group', 'all' ].
• includeDeleted - Indicates that results should include tombstoned / deleted items. Please see findDeletedObject for additional notes and caveats.
• entryParser - Allows for a custom function to be specified for parsing of the resulting ldap object. Examples include augmenting ldap data with external data from an RDBMs. function onParse(entry, raw, callback) { callback(entry); } If null is returned, the result is excluded.

Example

var opts = {
  scope: 'sub',
  filter: 'objectClass=User',
  includeMembership: [ 'user' ],
  entryParser: function(entry, raw, callback) {
    // returning null with exclude result
    if (entry.ignore) return(null);

    entry.retrievedAt = new Date();
    entry.preferredServer = getPreferredServerFromDatabase(entry.userPrincipalName);

    callback(entry);  
  }
};