easy-ldap-auth v1.0.0

easy-ldap-auth

Wrapper for the ldapjs library that makes LDAP authentication easy, with just enough options. Inspired by ldap-authentication.

Why?

I wanted a package that was straightforward to use, with a clean and modern codebase. So I wrote this.

Features

• :sparkles: Easy to use, with a clean API.
• :wrench: Full type definitions.
• :shield: Consistent errors.
• :bug: Easy debugging with logs provided by the debug package.
• :rocket: Used in production.

Installation

npm install easy-ldap-auth

Usage

let { singleAuthentication, singleSearch, InvalidUserCredentialsError } = require('easy-ldap-auth');

async function authenticate(username, password) {
    try {
        let user = await singleAuthentication({
            url: 'ldap://ldap.forumsys.com:389',
            adminDn: 'cn=read-only-admin,dc=example,dc=com',
            adminPassword: 'password',
            userSearchBaseDn: 'dc=example,dc=com',
            userSearchAttribute: 'uid',
            username,
            password,
        });
        // bind success, `user` is the user LDAP entry.
        return user;
    } catch (error) {
        if (error instanceof InvalidUserCredentialsError) {
            // invalid user credentials
            return null;
        } else {
            // ldapjs errors, like: admin bind error, connection error or timeout
            throw error;
        }
    }
}

async function searchUser(username) {
    try {
        let user = await singleSearch({
            url: 'ldap://ldap.forumsys.com:389',
            adminDn: 'cn=read-only-admin,dc=example,dc=com',
            adminPassword: 'password',
            userSearchBaseDn: 'dc=example,dc=com',
            userSearchAttribute: 'uid',
            username,
        });
        // `user` is the user LDAP entry or null if not found.
        return user;
    } catch (error) {
        // ldapjs errors, like: admin bind error, connection error or timeout
    }
}

Running tests

Clone this repository, then run npm install and then npm test. An internet connection is required as the forumsys' public LDAP server is used for testing.

API

singleSearch(options)

Perform a single search in a LDAP server. First, it binds as an admin user, then searchs for the given username in a given baseDn, and unbind the admin connection.

Returns a Promise that resolves to the user LDAP entry if it is found, or null if it wasn't.

singleAuthentication(options)

Perform a single authentication agains a LDAP server. First, it binds as an admin user, then searchs for the given username in a given baseDn, and unbind the admin connection. If the user is found, the function tries to bind to that user, resolving to the previous info if success, and then unbinding the user. If anything goes wrong, it throws an error. If the credentials for the user are invalid, it throws an InvalidUserCredentialsError.

Returns a Promise that resolves to the user LDAP entry if the credentials are valid, or rejects with an InvalidUserCredentialsError (see below) if the credentials are invalid.

Objects

SingleSearchOptions

SingleAuthenticationOptions (extends SingleSearchOptions)

InvalidUserCredentialsError (extends Error)

License

This sotftware is MIT licensed. Please check the LICENSE file for the full text.