liberkee / openldapjs

node.js wrapper for openLDAP C client libraries

OpenLDAP.JS

Development

Master

Node.js wrapper for OpenLDAP. This library allows you to interact through Node.js with a LDAP backend.

Getting Started

• Clone or download repository.
• Install dependencies.
• V8 Embedder's guide Useful documentation + examples if you want a deeper look at how embedding is done.
• Nan Nan examples, documentation and source.
• LDAP & OpenLDAP documentation and resources.

Prerequisites

• Install all dependencies :
  • Node.js(>version 4.8.5)
  • NPM
  • OpenLDAP libraries
  • Nan
  • V8

Why a new library?

Previous implementations lacked certain details such as extended operations' post/pre read which is something we needed dearly. Additionally, other libraries re-implemented the entire protocol (or rather chunks of it) and held the door open for various errors. Relying on the standard openldap C libraries should allow us to be more compatible with openldap servers than other libraries. Adding missing function calls to the interface should be easy due to pre-existing examples and not having to worry about the implementation on the protocol.

Building

OpenLDAP.js requires OpenLDAP development libraries.

Debian/Ubuntu

• OpenLDAP development libraries : sudo apt-get install libldap2-dev currently built with Openldap 2.4.45.
• Make sure you have python2.7 and node-gyp installed. Run npm install, it should install dependencies and build the c++ source files.

MacOs

• N/a yet.

Windows

• N/a yet.

Testing

For the tests to run, you'll need some sample test data. In order to do this manually edit the ldapAuthentication section of the config file and configure your local ldap data :

• host: address of your ldap server, E.g: ldap://localhost:389

• userDn: LDAP login Dn, this will be used for authentication. E.g: cn=admin,dc=demoApp,dc=com

• userPassword: Password for your userDn

Also, configure the ldapTestEntries section in order to tell it where to put the test data:

• entryDn: Entry point for your test data, E.g: cn=newPoint,o=myhost,dc=demoApp,dc=com

Make sure the user you're providing has sufficient rights (read/write).

After you're done configuring, run npm run addData, this should add 10k test entries to your ldap Server.

After the sample data is ready, run npm test and the tests should run.

npm test

Test breakdown

The tests are mainly designed for testing all ldap routines (add,delete,search,modify, initialize,bind, unbind, start tls, etc.). Test suite is composed of integration + unit tests.

Deployment

Clone or download the repository. Get all required packages with npm and build the addon files : npm install

The Node.JS wrapper for the library is libs/ldap_async_wrap.js, require it in your software like :

const LdapClient = require('openldapjs').Client;

A normal workflow would be :

const ldapClientInstance = new LdapClient('ldap://your_ldap_server:PORT');

ldapClientInstance.initialize()
    .then(() => {
      return ldapClientInstance.bind(userDn,userPassword)
    })
    .then( () => {
      ldapClientInstance.search(...);
      ldapClientInstance.add(...);
      ldapClientInstance.delete(...);
      ldapClientInstance.modify(...);
    });

For more in depth examples please consult Tests and Samples.

Built With

• Node-Gyp

Contributing

This project follows the airbnb lint rules for javascript and Clang google style for the C/C++ addon files. For easier collaboration, please ensure that your code is properly linted/formated before submitting a pull request.

Any pull requests or issue reports are appreciated.

Authors

Reviewers:

• Michael de Paly
• Philipp Tusch
• Yogesh Patel

Developers:

• Cosmin Ghitea
• Maxim Rotaru
• Radu Aribasoiu

See also the list of contributors who participated in this project.

License

• This Project is published under the MIT License
• All references: Licenses in use

Acknowledgments

• Hat tip to anyone who's code was used
• node-ldapjs
• Nan and v8
• OpenLDAP

openldapjs's Issues

Documentation needs actual examples of function calls and the output

To allow a 3rd party to develop this tool nicely, we should enrich the documentation to also have small sample passage with the most common and complex call we can find.

Seeing working code is a lot more helpful than an abstract documentation.

Modify: multiple attributes with same name

It doesn't seem to be possible to add another attributeName with an existing attribute name to an object.
Doing a test with ApacheDirectoryStudio shows that adding a second attribute with the same name is valid but the library doesn't seem to be capable to do so.

The operation was changed to add.

Create a modify sample with post/pre-read examples

To show how the well the controls are supported, we should showcase that in the documentation and let people know how that is done.

Pass options to ldap operations

Currently, we don't pass any options to ldap operations but that should be done.
One major issue is the timeout. This seems too be hardcoded on C.
Other options that should be passed are limit of results.

Maybe go to ldapjs and steal some ideas.
Having hardcoded timeouts actually breaks the benchmark :(

Mark errorcodes as instance member

To allow a 3rd party user to use own LDAP error classes and a dispenser, pass the native LDAP Error code through there.
So instead of a class member, we also have an instance member there which refers to the class member.

E.G.:

class MyError {
  static get code() {
    return 42;
  }

  get code() {
    return MyError.code;
  }
}

Remove startTLS from tests

The problem with the test is when a user don't have set the TLS communication on server and what to test the library. All tests will fail because they try to start a TLS communication. The fix will be to remove from almost all test the call for startTLS.

LDIF module

The problem with the LDIF module is that it don't take a dn with empty string from a string.
A solution is placed into the module and the issue is created too:

• Issue: tapmodo/node-ldif#6
• Pull request: tapmodo/node-ldif#7

Modify operations as enum

We do validate the inserted entries using json schema. For the operations on modify we should reference an enum since there are only a few usable values for op.

Check out change_schema.json and add an enum field.

Please use generic name as user for sample(s)

https://github.com/hufsm/openldapjs/blob/d731991f6f9e915dbc9631034d2f8b8477fa101b/sample/extended_operation.js#L20

Error While rebuilding on new branch

After i branched out of development i got the following error 👍

I encountered it after npm install without doing any modifications to the c++ code. Should be easy to reproduce. I'm guessing it pops up because we're putting a v8 local value that's locally scoped inside a structure that's used for the request, might cause segfaults down the path.

ldap search: optional filter

When doing an ldap search, one may specify a filter.
This filter seems to be a required value even though it may be pointless.

Is it possible to drop it and mark is as optional?

Tests are not independent of each other

Tests should have a cleanup and setup phase.

Name of package in package.json wrong

Ther name in the package json is wrong.
It states "ldapjswrapper" but should be "openldapjs" so you can require it with const OpenLdap = require('openldapjs')

Inferior URI Specification results in unknown error (80)

When you connect to your LDAP server without the proper uri prefix (ldap/ldaps) you'll see that you can't connect and LDAP populates the fllowing error:
80:Indicates an unknown error condition. This is the default value for NDS error codes which do not map to other LDAP error codes.

This is very poor since having an explicit error would be far better (wrongUriError or whatever)