Active Directory integration in Node.js

Everything in the previous pages works against Active Directory, but AD has a handful of specifics worth knowing before you connect to it. The full conceptual background lives in Active Directory — this page focuses on what changes in your ldapjs code.

An Active Directory base DN is derived from the domain name, not chosen freely. For a domain named corp.example.com, the base DN is dc=corp,dc=example,dc=com.

const client = ldap.createClient({ url: "ldaps://dc1.corp.example.com:636" });
const baseDn = "DC=corp,DC=example,DC=com";

Active Directory supports two common login identifiers:

• sAMAccountName — the legacy, pre-Windows-2000 short username (e.g. jdoe).
• userPrincipalName — the modern, email-shaped identifier (e.g. jdoe@corp.example.com).

Search for whichever one your login form actually collects:

const filter = `(sAMAccountName=${escapeFilterValue(username)})`;
// or
const filter = `(userPrincipalName=${escapeFilterValue(username)})`;

Unlike most attributes, objectGUID (a unique identifier for the object) and objectSid (the security identifier) are returned as raw binary buffers, not strings. If you need to display or store them, decode them explicitly rather than treating them as UTF-8 text — mis-decoding these is a common source of subtle bugs when migrating code from other directories.

Active Directory encodes account status inside the userAccountControl bitmask attribute rather than as separate boolean fields. A commonly checked bit is 0x2 (ACCOUNTDISABLE). Rather than parsing this bitmask by hand in every codebase, many teams instead rely on the bind itself failing with a decodable extended error — see Authentication in Active Directory.

Large, multi-domain AD forests can return referrals — pointers to continue a search on a different domain controller. ldapjs does not chase referrals automatically by default; for most single-domain deployments this never comes up, but it's worth knowing if searches against a large forest come back incomplete.

Before shipping any of this, review Production security with ldapjs for TLS and credential-handling practices.