Home

Awesome

A Simple node Library that Authenticates a User Against an LDAP/AD Server

Integration Tests Known Vulnerabilities NPM Weekly Downloads

Goal

Make authentication with an LDAP server easy.

Description

This library use ldapjs as the underneath library. It has three modes of authentications:

  1. Admin authenticate mode. If an admin user is provided, the library will login (ldap bind) with the admin user, then search for the user to be authenticated, get its DN (distinguish name), then use the user DN and password to login again. If every thing is ok, the user details will be returned.

  2. Self authenticate mode. If the admin user is not provided, then the userDn and userPassword must be provided. If any of userSearchBase or usernameAttribute is missing, then the lib simply does a login with the userDn and userPassword (ldap bind), and returns true if succeeds.

    Otherwise, the lib does a login with the userDn and userPassword (ldap bind), then does a search on the user and return the user's details.

  3. Verify user exists. If an verifyUserExists : true is provided, the library will login (ldap bind) with the admin user, then search for the user to be verified. If the user exists, user details will be returned (without verifying the user's password).

Features

Usage

Installation

npm install ldap-authentication --save

Examples

User authenticate without getting user details

let authenticated = await authenticate({
  ldapOpts: { url: 'ldap://ldap.forumsys.com' },
  userDn: 'uid=gauss,dc=example,dc=com',
  userPassword: 'password',
})

User authenticate and return user details

let authenticated = await authenticate({
  ldapOpts: { url: 'ldap://ldap.forumsys.com' },
  userDn: 'uid=gauss,dc=example,dc=com',
  userPassword: 'password',
  userSearchBase: 'dc=example,dc=com',
  usernameAttribute: 'uid',
  username: 'gauss',
  attributes: ['dn', 'sn', 'cn'],
})

User exists verification and return user details (without user's password)

let authenticated = await authenticate({
  ldapOpts: { url: 'ldap://ldap.forumsys.com' },
  userDn: 'uid=gauss,dc=example,dc=com',
  verifyUserExists: true,
  userSearchBase: 'dc=example,dc=com',
  usernameAttribute: 'uid',
  username: 'gauss',
})

User authenticate and return user details with groups

let authenticated = await authenticate({
  ldapOpts: { url: 'ldap://ldap.forumsys.com' },
  userDn: 'uid=gauss,dc=example,dc=com',
  userPassword: 'password',
  userSearchBase: 'dc=example,dc=com',
  usernameAttribute: 'uid',
  username: 'gauss',
  groupsSearchBase: 'dc=example,dc=com',
  groupClass: 'groupOfUniqueNames',
  groupMemberAttribute: 'uniqueMember',
  // groupMemberUserAttribute: 'dn'
})

Complete example

const { authenticate } = require('ldap-authentication')

async function auth() {
  // auth with admin
  let options = {
    ldapOpts: {
      url: 'ldap://ldap.forumsys.com',
      // tlsOptions: { rejectUnauthorized: false }
    },
    adminDn: 'cn=read-only-admin,dc=example,dc=com',
    adminPassword: 'password',
    userPassword: 'password',
    userSearchBase: 'dc=example,dc=com',
    usernameAttribute: 'uid',
    username: 'gauss',
    // starttls: false
  }

  let user = await authenticate(options)
  console.log(user)

  // auth with regular user
  options = {
    ldapOpts: {
      url: 'ldap://ldap.forumsys.com',
      // tlsOptions: { rejectUnauthorized: false }
    },
    userDn: 'uid=einstein,dc=example,dc=com',
    userPassword: 'password',
    userSearchBase: 'dc=example,dc=com',
    usernameAttribute: 'uid',
    username: 'einstein',
    // starttls: false
  }

  user = await authenticate(options)
  console.log(user)
}

auth()

Parameters

Returns

The user object if authenticate() is success.

In version 2, The user object has a raw field that has the raw data from the LDAP/AD server. It can be used to access buffer objects (profile pics for example).

Buffer data can now be accessed by user.raw.profilePhoto, etc, instead of user.profilePhoto.

In version 3, the raw field is no longer used. Instead, append ;binary to the attributes you want to get back as base64-encoded string. Check the following example on how to get a user's profile photo:

export async function verifyLogin(email: string, password: string) {

  const options = {
   //...other config options
    userPassword: password,
    username: email,
    attributes: ['thumbnailPhoto;binary', 'givenName', 'sn', 'sAMAccountName', 'userPrincipalName', 'memberOf' ]
  };

  try {
    const ldapUser = await authenticate(options);

    if (!ldapUser) {
      return { error: "user not found" };
    }

    // accessing the image
    const profilePhoto = ldapUser['thumbnailPhoto;binary'];

    /* using the image
	<img src={`data:image/*;base64,${profilePhoto}`} />
    */
    return { user: ldapUser };
  }
}

Supported Node Versions

Version 2 supports Node version 12, 14, 15, 16, 17 and 18.

Version 3 supports Node version 16, 17, 18, 20 and 22,