AD2
Making Active Directory jQuery-easy.
AD2 is an extension of the original AD package and a Javascript implementation of common Active Directory tasks, built to be simple as possible.
Really simple.
You can use async
/ await
:
async { try await ad; await ad; await ad; catcherr // ... };
Or stick with promises:
ad\ ;
Features
- Robust
user
,group
andou
manipulation methods - High and low-level search methods
- Caching by default
- Fancy result filtering including column and value filtering, sorting and pagination
- Companion drop-in REST API
Getting Started
First, install the library:
npm i ad
yarn add ad
Then add this to index.js
:
const AD = ; // Your AD account should be a member// of the Administrators group.const ad = url: "ldaps://127.0.0.1" user: "dthree@acme.co" pass: "howinsecure"; ad;
Now run the file:
node index.js
And you're off to the races.
API
adadadadadadadadadadadadadadadadadlocation adadadadadadad adadadadad adobjectadobjectadobjectobjectName locationadobjectobjectName locationadobjectobjectName locationadobjectobjectName locationadobjectobjectName location adadallad adad
User Methods
ad.user().get(filter)
Returns all user objects.
await ad;// => ['jsmith', 'dthree', 'qix'];
ad.user().add(options)
Creates a new user. Returns the created user object.
Options:
userName
: String (required)pass
: String (required)commonName
: String (required)firstName
: StringlastName
: Stringemail
: Stringtitle
: Stringlocation
: String
If not specified, the first and last name will be based on the commonName
.
await ad;// => {sAMAccountName: 'jsmith' ... }
ad.user(userName).get(filter)
Returns a user object. If no user is matched, returns undefined
.
await ad;// => {sAMAccountName: 'jsmith', email: 'jsmith@acme.co' ... }
ad.user(userName).exists()
Returns a Boolean
of whether the user account matched.
await ad;// => false
ad.user(userName).addToGroup(groupName)
Adds a user to a security group.
await ad;// => {success: true}
ad.user(userName).removeFromGroup(groupName)
Removes a user from a security group.
await ad;// => {success: true}
ad.user(userName).isMemberOf(groupName)
Returns a Boolean
based on whether the user is a member of a group.
await ad;// => true
ad.user(userName).authenticate(password)
Attempts to authenticate a user with a given password. Returns Boolean
.
await ad;// => true
ad.user(userName).password(password)
Sets a user's password.
await ad;// => true
ad.user(userName).passwordNeverExpires()
Sets a user's to never expire.
await ad;// => {success: true}
ad.user(userName).passwordExpires()
Unchecks the "Password never expires" box.
await ad;// => {success: true}
ad.user(userName).enable()
Enables a user.
await ad;// => {success: true}
ad.user(userName).disable()
Disables a user.
await ad;// => {success: true}
ad.user(userName).unlock()
Unlocks a user who has been locked out by repeated failed login attempts.
await ad;// => {success: true}
ad.user(userName).lock()
Just kidding. You can't lock an account. Try disabling it instead.
await ad;// => {success: true}
ad.user(userName).move(location)
Moves a user to another directory, starting from the root of the domain.
await ad;// => {success: true}
This is the equivalent of acme.co => Users (OU) => HR (OU)
. The new Distinguished Name
(DN) would become CN=John Smith,OU=HR,OU=Users,DC=acme,DC=co
.
To specify a folder that is not an Organizational Unit, prefix it with !
:
await ad;// => {success: true}
ad.user(userName).location()
Returns a user's relative location, separated by /
es.
await adlocation;// => 'Users/HR'
ad.user(userName).remove()
Deletes a user. Are you sure you want to do this?
await ad;// => {success: true}
Group Methods
ad.group().get(filter)
Returns all group objects.
await ad;// => [{ ... }, { ... }];
ad.group().add(options)
Creates a new group. Returns the created group object.
Options:
name
: String (required)location
: Stringdescription
: String
await ad;// => {sAMAccountName: 'HR' ... }
ad.group(groupName).get(filter)
Returns a group object. If no group is matched, returns undefined
.
await ad;// => {sAMAccountName: 'HR', description: 'Human...' ... }
ad.group(groupName).exists()
Returns a Boolean
of whether the group account matched.
await ad;// => false
ad.group(groupName).addUser(groupName)
Adds a user to a group.
await ad;// => {success: true}
ad.group(groupName).removeUser(groupName)
Removes a user from a group.
await ad;// => {success: true}
ad.group(groupName).remove()
Deletes a group.
await ad;// => {success: true}
Organizational Unit (OU) Methods
ad.ou().get(filter)
Returns all ou objects.
await ad;// => [{ ... }, { ... }];
ad.ou().add(options)
Creates a new Organizational Unit. Returns the created OU object.
Options:
name
: String (required)location
: Stringdescription
: String
await ad;// => {ou: 'Sales' ... }
ad.ou(ouName).get(filter)
Returns an OU object. If no OU is matched, returns undefined
.
await ad;// => {ou: 'Sales', description: 'Sales...' ... }
ad.ou(ouName).exists()
Returns a Boolean
of whether the OU exists.
await ad;// => true
ad.user(userName).remove()
Deletes an Organizational Unit. As a note, if it has any children, this will not work.
await ad;// => {success: true}
Object methods
ad.object().get(filter)
Returns all objects that are not users or groups.
await ad;// => [{ ... }, { ... }];
ad.object().add(options)
Creates a new object in Active Directory. Returns the created object.
await adobject// => { cn: "My Phone", objectClass: "device" }
ad.object(objectName).get()
Returns an object that is not a user or a group with the given name. If no object is matched, returns undefined
.
await adobject"My Object"// => { cn: "My Object", description: "Something something..." ... }
ad.object(objectName, location).get()
Returns an object that is not a user or a group with the given name at the given location. If no object is matched, returns undefined
.
await adobject"My Object" "SomeOU"// => { cn:"My Object", description: "Something something..." ... }
ad.object(objectName).remove()
Removes an object from the Active Directory. (Warning: Uses first match across all OUs when no location is given)
await adobject"My Object"// => { success: true }
ad.object(objectName, location).remove()
Removes an object from the Active Directory at the given location.
await adobject"My Object" "SomeOU"// => { success: true }
ad.object(objectName).addToGroup(groupName)
Adds an object to a group in Active Directory.
await adobject"My Object"// => { success: true }
ad.object(objectName, location).addToGroup(groupName)
Adds an object at the given location to a group in Active Directory.
await adobject"My Object" "SomeOU"// => { success: true }
ad.object(objectName).setProperties(properties)
Updates already existing properties of the given object in Active Directory.
await adobject"My Object"// => { success: true }
ad.object(objectName, location).setProperties(properties)
Updates already existing properties of the given object at the given location in Active Directory.
await adobject"My Object" "SomeOU"// => { success: true }
Other methods
ad.other().get(filter)
Returns all objects that are not users or groups.
await ad;// => [{ ... }, { ... }];
ad.all().get(filter)
Returns all objects in the Active Directory instance, grouping by users
, groups
and other
.
await ad;// => [users: [...], groups: [...], other: [...]];
ad.find(searchString)
Returns a raw search of the entire Active Directory.
await ad;// => [{...}, {...}];
Caching
ad.cache(boolean)
Enables or disables caching. Defaults to true
.
ad;
ad.cacheTimeout(millis)
Sets the amount of milliseconds before a cached item expires. Defaults to ten minutes. Chainable to ad.cache
.
ad;
Why?
Active Directory / LDAP can be hard. Some of us are stuck with it.
Should you really have to know that cn
stands for Common Name
(or was it Canonical
) in order to use it? Or that sn
is a surname
*? I dislike systems that require detailed knowledge of their dirty laundry to do anything with them.
So this was a selfish project, really.
Made with <3 by dthree.
*last name
License
MIT