ActiveDirectory is an ldapjs client for authN (authentication) and authZ (authorization) for Microsoft Active Directory with range retrieval support for large Active Directory installations.
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
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.
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 onvar sAMAccountName = 'username';var userPrincipalName = 'username@domain.com';var dn = 'CN=Smith\\, John,OU=Users,DC=domain,DC=com';// Find user by a sAMAccountNamevar 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.'
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 onvar groupName = 'Employees';var dn = 'CN=Employees,OU=Groups,DC=domain,DC=com'// Find group by common namevar 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.
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); }};
group - distinguishedName, objectCategory, cn, description
If you need to override those defaults, then you can override them when you create your ActiveDirectory instance:
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' ] } });
If overriding the 'user' or 'group' attribute, you must specify ALL of the attributes you want. The existing defaults
will be overridden. Optionally, you can override the attributes on a per call basis using the 'opts' parameter.
Referrals
By default, referral chasing is disabled. To enable it, specify a referrals attribute when you create your instance.
The referrals object has the following syntax:
The 'excluded' options is a list of regular expression filters to ignore specific referrals. The default exclusion list
is included above, ignoring the special partitions that ActiveDirectory creates by default. To specify these options,
override them as follows:
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: [ ] } });
If you enable referral chasing, the specified username MUST be a userPrincipalName.
Custom Entry Parsing
if you want to manipulate the search entry in a different way or perhaps augment the search
result with additional data, you can pass a custom parser. This is useful, for example, in case
you want to change the objectSid or GUID which are binary values.
Example:
function customEntryParser(entry, raw, callback){ if (raw.hasOwnProperty("objectSid")){ entry.objectSid = raw.objectSid; } if (raw.hasOwnProperty("objectGUID")){ entry.objectGUID = raw.objectGUID; } callback(entry);};
If you want to specify your own parser you can override the default parser as follows:
var ad = new ActiveDirectory({ url: 'ldap://dc.domain.com', baseDN: 'dc=domain,dc=com', username: 'username@domain.com', password: 'password', attributes: { ... }, referrals: { ... }, entryParser : customEntryParser });