{"id":13527448,"url":"https://github.com/ldapts/ldapts","last_synced_at":"2026-02-02T11:16:02.621Z","repository":{"id":39365744,"uuid":"155400905","full_name":"ldapts/ldapts","owner":"ldapts","description":"LDAP client written in typescript","archived":false,"fork":false,"pushed_at":"2025-03-27T18:25:48.000Z","size":1316,"stargazers_count":226,"open_issues_count":8,"forks_count":39,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-27T19:33:24.749Z","etag":null,"topics":["hacktoberfest","hacktoberfest2022","hacktoberfest2023","ldap","nodejs"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ldapts.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["jgeurts"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2018-10-30T14:37:32.000Z","updated_at":"2025-03-27T18:25:51.000Z","dependencies_parsed_at":"2023-10-05T16:45:37.617Z","dependency_job_id":"6b9d4bf7-b60d-48c4-a27d-9dbefb6163f6","html_url":"https://github.com/ldapts/ldapts","commit_stats":{"total_commits":177,"total_committers":17,"mean_commits":"10.411764705882353","dds":"0.21468926553672318","last_synced_commit":"61769495b1839fa6d8fa2a44f02a2f721580e800"},"previous_names":[],"tags_count":78,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ldapts%2Fldapts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ldapts%2Fldapts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ldapts%2Fldapts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ldapts%2Fldapts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ldapts","download_url":"https://codeload.github.com/ldapts/ldapts/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246616132,"owners_count":20806064,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest","hacktoberfest2022","hacktoberfest2023","ldap","nodejs"],"created_at":"2024-08-01T06:01:48.233Z","updated_at":"2025-12-24T08:48:40.938Z","avatar_url":"https://github.com/ldapts.png","language":"TypeScript","funding_links":["https://github.com/sponsors/jgeurts"],"categories":["TypeScript"],"sub_categories":[],"readme":"# LDAPts\n\n[![NPM version](https://img.shields.io/npm/v/ldapts.svg?style=flat)](https://npmjs.org/package/ldapts)\n[![node version](https://img.shields.io/node/v/ldapts.svg?style=flat)](https://nodejs.org)\n[![Known Vulnerabilities](https://snyk.io/test/npm/ldapts/badge.svg)](https://snyk.io/test/npm/ldapts)\n\nProviding an API to access LDAP directory servers from Node.js programs.\n\n## Table of Contents\n\n- [API Details](#api-details)\n  - [Create a client](#create-a-client)\n  - [Specifying Controls](#specifying-controls)\n  - [bind](#bind)\n  - [startTLS](#starttls)\n  - [add](#add)\n  - [compare](#compare)\n  - [del](#del)\n  - [exop](#exop)\n  - [modify](#modify)\n    - [Change](#change)\n  - [modifyDN](#modifydn)\n  - [search](#search)\n    - [Filter Strings](#filter-strings)\n    - [Return buffer for specific attribute](#return-buffer-for-specific-attribute)\n  - [searchPaginated](#searchpaginated)\n  - [unbind](#unbind)\n- [Usage Examples](#usage-examples)\n  - [Authenticate example](#authenticate-example)\n  - [Search example](#search-example)\n  - [Delete Active Directory entry example](#delete-active-directory-entry-example)\n- [Configuring Secure Connections](#configuring-secure-connections)\n- [Common Errors](#common-errors)\n- [Development](#development)\n  - [Start test OpenLDAP server](#start-test-openldap-server)\n  - [Close test OpenLDAP server](#close-test-openldap-server)\n\n## API details\n\n### Create a client\n\nThe code to create a new client looks like:\n\n```ts\nimport { Client } from 'ldapts';\n\nconst client = new Client({\n  url: 'ldaps://ldap.jumpcloud.com',\n  timeout: 0,\n  connectTimeout: 0,\n  tlsOptions: {\n    minVersion: 'TLSv1.2',\n  },\n  strictDN: true,\n});\n```\n\nYou can use `ldap://` or `ldaps://`; the latter would connect over SSL (note\nthat this will not use the LDAP TLS extended operation, but literally an SSL\nconnection to port 636, as in LDAP v2). The full set of options to create a\nclient is:\n\n| Attribute      | Description                                                                                |\n| -------------- | ------------------------------------------------------------------------------------------ |\n| url            | A valid LDAP URL (proto/host/port only)                                                    |\n| timeout        | Milliseconds client should let operations live for before timing out (Default: Infinity)   |\n| connectTimeout | Milliseconds client should wait before timing out on TCP connections (Default: OS default) |\n| tlsOptions     | TLS [connect() options](https://nodejs.org/api/tls.html#tls_tls_connect_options_callback)  |\n| strictDN       | Force strict DN parsing for client methods (Default is true)                               |\n\n### Specifying Controls\n\nSingle or an array of `Control` objects can be added to various operations like the following:\n\n```ts\nimport { Control } from 'ldapts/controls';\n\nconst { searchEntries, searchReferences } = await client.search(\n  searchDN,\n  {\n    filter: '(mail=peter.parker@marvel.com)',\n  },\n  new Control('1.2.840.113556.1.4.417'),\n);\n```\n\nYou can also subclass `Control` for finer control over how data is parsed and written.\nLook at [PagedResultsControl](src/controls/PagedResultsControl.ts) for an example.\n\n### bind\n\n`bind(dnOrSaslMechanism, [password], [controls])`\n\nPerforms a bind operation against the LDAP server.\n\nArguments:\n\n| Argument                              | Description                                                                                                     |\n| ------------------------------------- | --------------------------------------------------------------------------------------------------------------- |\n| `dnOrSaslMechanism` (string)          | The name (DN) of the directory object that the client wishes to bind as or the SASL mechanism (PLAIN, EXTERNAL) |\n| `[password]` (string)                 | Password for the target bind DN. For SASL this is instead an optional set of encoded SASL credentials.          |\n| `[controls]` (Control\u0026#124;Control[]) | Optional `Control` object or array of `Control` objects                                                         |\n\nSimple Example:\n\n```ts\nawait client.bind('cn=root', 'secret');\n```\n\nSASL Example:\n\n```ts\n// No credentials\nawait client.bind('EXTERNAL');\n\n// With credentials\nconst credentials = '...foo...';\nawait client.bind('PLAIN', credentials);\n```\n\n### startTLS\n\n`startTLS(options, [controls])`\n\nPerforms a StartTLS extended operation against the LDAP server to initiate a TLS-secured communication channel over an\notherwise clear-text connection.\n\nArguments:\n\n| Argument                              | Description                                                                               |\n| ------------------------------------- | ----------------------------------------------------------------------------------------- |\n| `options` (object)                    | TLS [connect() options](https://nodejs.org/api/tls.html#tls_tls_connect_options_callback) |\n| `[controls]` (Control\u0026#124;Control[]) | Optional `Control` object or array of `Control` objects                                   |\n\nExample:\n\n```ts\nawait client.startTLS({\n  ca: [fs.readFileSync('mycacert.pem')],\n});\n```\n\n### add\n\n`add(dn, entry, [controls])`\n\nPerforms an add operation against the LDAP server.\n\nAllows you to add an entry (as a js object or array of Attributes), and as always,\ncontrols are optional.\n\nArguments:\n\n| Argument                              | Description                                             |\n| ------------------------------------- | ------------------------------------------------------- |\n| `dn` (string)                         | The DN of the entry to add                              |\n| `entry` (object\u0026#124;Attribute[])     | The set of attributes to include in that entry          |\n| `[controls]` (Control\u0026#124;Control[]) | Optional `Control` object or array of `Control` objects |\n\nExample:\n\n```ts\nvar entry = {\n  cn: 'foo',\n  sn: 'bar',\n  email: ['foo@bar.com', 'foo1@bar.com'],\n  objectclass: 'fooPerson',\n};\nawait client.add('cn=foo, o=example', entry);\n```\n\n### compare\n\n`compare(dn, attribute, value, [controls])`\n\nPerforms an LDAP compare operation with the given attribute and value against\nthe entry referenced by dn.\n\nArguments:\n\n| Argument                              | Description                                                             |\n| ------------------------------------- | ----------------------------------------------------------------------- |\n| `dn` (string)                         | The DN of the entry in which the comparison is to be made               |\n| `attribute` (string)                  | The Name of the attribute in which the comparison is to be made         |\n| `value` (string)                      | The Attribute Value Assertion to try to find in the specified attribute |\n| `[controls]` (Control\u0026#124;Control[]) | Optional `Control` object or array of `Control` objects                 |\n\nReturns:\n`(boolean)`: Returns `true` if the target entry exists and does contain the specified attribute value; otherwise `false`\n\nExample:\n\n```ts\nconst hasValue = await client.compare('cn=foo, o=example', 'sn', 'bar');\n```\n\n### del\n\n`del(dn, [controls])`\n\nDeletes an entry from the LDAP server.\n\nArguments:\n\n| Argument                              | Description                                             |\n| ------------------------------------- | ------------------------------------------------------- |\n| `dn` (string)                         | The DN of the entry to delete                           |\n| `[controls]` (Control\u0026#124;Control[]) | Optional `Control` object or array of `Control` objects |\n\nExample:\n\n```ts\nawait client.del('cn=foo, o=example');\n```\n\n### exop\n\n`exop(oid, [value], [controls])`\n\nPerforms an LDAP extended operation against an LDAP server.\n\nArguments:\n\n| Argument                              | Description                                             |\n| ------------------------------------- | ------------------------------------------------------- |\n| `oid` (string)                        | Object identifier representing the type of request      |\n| `[value]` (string)                    | Optional value - based on the type of operation         |\n| `[controls]` (Control\u0026#124;Control[]) | Optional `Control` object or array of `Control` objects |\n\nExample (performs an LDAP 'whoami' extended op):\n\n```ts\nconst { value } = await client.exop('1.3.6.1.4.1.4203.1.11.3');\n```\n\n### modify\n\n`modify(name, changes, [controls])`\n\nPerforms an LDAP modify operation against the LDAP server. This API requires\nyou to pass in a `Change` object, which is described below. Note that you can\npass in a single `Change` or an array of `Change` objects.\n\nArguments:\n\n| Argument                              | Description                                             |\n| ------------------------------------- | ------------------------------------------------------- |\n| `dn` (string)                         | The DN of the entry to modify                           |\n| `changes` (Change\u0026#124;Change[])      | The set of changes to make to the entry                 |\n| `[controls]` (Control\u0026#124;Control[]) | Optional `Control` object or array of `Control` objects |\n\nExample (update multiple attributes):\n\n```ts\nimport { Attribute, Change } from 'ldapts';\n\nawait client.modify('cn=foo, o=example', [\n  new Change({ operation: 'replace', modification: new Attribute({ type: 'title', values: ['web tester'] }) }),\n  new Change({ operation: 'replace', modification: new Attribute({ type: 'displayName', values: ['John W Doe'] }) }),\n]);\n```\n\nExample (update binary attribute):\n\n```ts\nimport { Attribute, Change } from 'ldapts';\n\nconst thumbnailPhotoBuffer = await fs.readFile(path.join(__dirname, './groot_100.jpg'));\n\nvar change = new Change({\n  operation: 'replace',\n  modification: new Attribute({\n    type: 'thumbnailPhoto;binary',\n    values: [thumbnailPhotoBuffer],\n  }),\n});\n\nawait client.modify('cn=foo, o=example', change);\n```\n\n#### Change\n\n`Change({ operation, modification })`\n\nA `Change` object maps to the LDAP protocol of a modify change, and requires you\nto set the `operation` and `modification`.\n\nArguments:\n\n| Argument                                   | Description                                 |\n| ------------------------------------------ | ------------------------------------------- |\n| `operation` (replace\u0026#124;add\u0026#124;delete) | _See table below_                           |\n| `modification` (Attribute)                 | Attribute details to add, remove, or update |\n\nOperations:\n\n| Value     | Description                                                                                                           |\n| --------- | --------------------------------------------------------------------------------------------------------------------- |\n| `replace` | Replaces the attribute referenced in `modification`. If the modification has no values, it is equivalent to a delete. |\n| `add`     | Adds the attribute value(s) referenced in `modification`. The attribute may or may not already exist.                 |\n| `delete`  | Deletes the attribute (and all values) referenced in `modification`.                                                  |\n\n### modifyDN\n\n`modifyDN(dn, newDN, [controls])`\n\nPerforms an LDAP modifyDN (rename) operation against an entry in the LDAP\nserver. A couple points with this client API:\n\n- There is no ability to set \"keep old dn.\" It's always going to flag the old\n  dn to be purged.\n- The client code will automatically figure out if the request is a \"new\n  superior\" request (\"new superior\" means move to a different part of the tree,\n  as opposed to just renaming the leaf).\n\n\u003c!-- markdownlint-disable line-length --\u003e\n\nArguments:\n\n| Argument                              | Description                                                                                                                                                                                                                                                        |\n| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `dn` (string)                         | The DN of the entry to rename                                                                                                                                                                                                                                      |\n| `newDN` (string)                      | The new RDN to use assign to the entry. It may be the same as the current RDN if you only intend to move the entry beneath a new parent. If the new RDN includes any attribute values that aren’t already in the entry, the entry will be updated to include them. |\n| `[controls]` (Control\u0026#124;Control[]) | Optional `Control` object or array of `Control` objects                                                                                                                                                                                                            |\n\n\u003c!-- markdownlint-enable line-length --\u003e\n\nExample:\n\n```ts\nawait client.modifyDN('cn=foo, o=example', 'cn=bar');\n```\n\n### search\n\n`search(baseDN, options, [controls])`\n\nPerforms a search operation against the LDAP server.\n\nThe search operation is more complex than the other operations, so this one\ntakes an `options` object for all the parameters.\n\nArguments:\n\n| Argument                              | Description                                                      |\n| ------------------------------------- | ---------------------------------------------------------------- |\n| `baseDN` (string)                     | The base of the subtree in which the search is to be constrained |\n| `options` (object)                    | _See table below_                                                |\n| `[controls]` (Control\u0026#124;Control[]) | Optional `Control` object or array of `Control` objects          |\n\n\u003c!-- markdownlint-disable line-length no-inline-html --\u003e\n\nOptions:\n\n| Attribute                                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |\n| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| [scope=sub] (string)                           | \u003cul\u003e\u003cli\u003e`base` - Indicates that only the entry specified as the search base should be considered. None of its subordinates will be considered.\u003c/li\u003e\u003cli\u003e`one` - Indicates that only the immediate children of the entry specified as the search base should be considered. The base entry itself should not be considered, nor any descendants of the immediate children of the base entry.\u003c/li\u003e\u003cli\u003e`sub` - Indicates that the entry specified as the search base, and all of its subordinates to any depth, should be considered.\u003c/li\u003e\u003cli\u003e`children` - Indicates that the entry specified by the search base should not be considered, but all of its subordinates to any depth should be considered.\u003c/li\u003e\u003c/ul\u003e                                                                                                                                                                                                                            |\n| [filter=(objectclass=*)] (string\u0026#124;Filter)  | The filter of the search request. It must conform to the LDAP filter syntax specified in RFC4515                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| [derefAliases=never] (string)                  | \u003cul\u003e\u003cli\u003e`never` - Never dereferences entries, returns alias objects instead. The alias contains the reference to the real entry.\u003c/li\u003e\u003cli\u003e`always` - Always returns the referenced entries, not the alias object.\u003c/li\u003e\u003cli\u003e`search` - While searching subordinates of the base object, dereferences any alias within the search scope. Dereferenced objects become the bases of further search scopes where the Search operation is also applied by the server. The server should eliminate duplicate entries that arise due to alias dereferencing while searching.\u003c/li\u003e\u003cli\u003e`find` - Dereferences aliases in locating the base object of the search, but not when searching subordinates of the base object.\u003c/li\u003e\u003c/ul\u003e                                                                                                                                                                                                                      |\n| [returnAttributeValues=true] (boolean)         | If true, attribute values should be included in the entries that are returned; otherwise entries that match the search criteria should be returned containing only the attribute descriptions for the attributes contained in that entry but should not include the values for those attributes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| [sizeLimit=0] (number)                         | The maximum number of entries that should be returned from the search. A value of zero indicates no limit. Note that the server may also impose a size limit for the search operation, and in that case the smaller of the client-requested and server-imposed size limits will be enforced.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| [timeLimit=10] (number)                        | The maximum length of time, in seconds, that the server should spend processing the search. A value of zero indicates no limit. Note that the server may also impose a time limit for the search operation, and in that case the smaller of the client-requested and server-imposed time limits will be enforced.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| [paged=false] (boolean\u0026#124;SearchPageOptions) | Used to allow paging and specify the page size. Note that even with paged options the result will contain all of the search results. If you need to paginate over results have a look at to [searchPaginated](#searchpaginated) method.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |\n| [attributes=] (string[])                       | A set of attributes to request for inclusion in entries that match the search criteria and are returned to the client. If a specific set of attribute descriptions are listed, then only those attributes should be included in matching entries. The special value “_” indicates that all user attributes should be included in matching entries. The special value “+” indicates that all operational attributes should be included in matching entries. The special value “1.1” indicates that no attributes should be included in matching entries. Some servers may also support the ability to use the “@” symbol followed by an object class name (e.g., “@inetOrgPerson”) to request all attributes associated with that object class. If the set of attributes to request is empty, then the server should behave as if the value “_” was specified to request that all user attributes be included in entries that are returned. |\n| [explicitBufferAttributes=] (string[])         | List of explicit attribute names to return as Buffer objects                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n\n\u003c!-- markdownlint-enable line-length no-inline-html --\u003e\n\nExample:\n\n```ts\nconst { searchEntries, searchReferences } = await client.search(searchDN, {\n  filter: '(mail=peter.parker@marvel.com)',\n});\n```\n\nPlease see [Client tests](https://github.com/ldapts/ldapts/blob/master/tests/Client.tests.ts) for more search examples\n\n### searchPaginated\n\n`search(baseDN, options, [controls])`\n\nPerforms a search operation against the LDAP server and retrieve results in a paginated way.\n\nThe searchPagination the same `options` with [search](#search) method but returns an iterator.\n\nExample:\n\n```ts\nconst paginator = client.searchPaginated('o=5be4c382c583e54de6a3ff52,dc=jumpcloud,dc=com', {\n  filter: 'objectclass=*',\n  paged: {\n    pageSize: 10,\n  },\n});\n\nlet total = 0;\nfor await (const searchResult of paginator) {\n  total += searchResult.searchEntries.length;\n  console.log(searchResult.searchEntries);\n}\n\nconsole.log(`total results: ${total}`);\n```\n\n#### Filter Strings\n\nThe easiest way to write search filters is to write them compliant with RFC2254,\nwhich is \"The string representation of LDAP search filters.\"\n\nAssuming you don't really want to read the RFC, search filters in LDAP are\nbasically are a \"tree\" of attribute/value assertions, with the tree specified\nin prefix notation. For example, let's start simple, and build up a complicated\nfilter. The most basic filter is equality, so let's assume you want to search\nfor an attribute `email` with a value of `foo@bar.com`. The syntax would be:\n\n```ts\nconst filter = `(email=foo@bar.com)`;\n```\n\nldapts requires all filters to be surrounded by '()' blocks. Ok, that was easy.\nLet's now assume that you want to find all records where the email is actually\njust anything in the \"@bar.com\" domain and the location attribute is set to\nSeattle:\n\n```ts\nconst filter = `(\u0026(email=*@bar.com)(l=Seattle))`;\n```\n\nNow our filter is actually three LDAP filters. We have an `and` filter (single\namp `\u0026`), an `equality` filter `(the l=Seattle)`, and a `substring` filter.\nSubstrings are wildcard filters. They use `*` as the wildcard. You can put more\nthan one wildcard for a given string. For example you could do `(email=*@*bar.com)`\nto match any email of @bar.com or its subdomains like \"\u003cexample@foo.bar.com\u003e\".\n\nNow, let's say we also want to set our filter to include a\nspecification that either the employeeType _not_ be a manager nor a secretary:\n\n```ts\nconst filter = `(\u0026(email=*@bar.com)(l=Seattle)(!(|(employeeType=manager)(employeeType=secretary))))`;\n```\n\nThe `not` character is represented as a `!`, the `or` as a single pipe `|`.\nIt gets a little bit complicated, but it's actually quite powerful, and lets you\nfind almost anything you're looking for.\n\n#### Return buffer for specific attribute\n\nSometimes you may want to get a buffer back instead of a string for an attribute value. Depending on the server software,\nyou may be able to append `;binary`\n(the [binary attribute subtype](https://docs.oracle.com/cd/E19424-01/820-4809/bcacz/index.html)) to the attribute name,\nto have the value returned as a Buffer.\n\n```ts\nconst searchResults = await ldapClient.search('ou=Users,o=5be4c382c583e54de6a3ff52,dc=jumpcloud,dc=com', {\n  filter: '(mail=peter.parker@marvel.com)',\n  attributes: ['jpegPhoto;binary'],\n});\n```\n\nHowever, some servers are very strict when it comes to the binary attribute subtype and will only acknowledge it if\nthere is an associated AN.1 type or valid BER encoding. In those cases, you can tell ldapts to explicitly return a\nBuffer for an attribute:\n\n```ts\nconst searchResult = await client.search('ou=Users,o=5be4c382c583e54de6a3ff52,dc=jumpcloud,dc=com', {\n  filter: '(mail=peter.parker@marvel.com)',\n  explicitBufferAttributes: ['jpegPhoto'],\n});\n```\n\n### unbind\n\n`unbind()`\n\nUsed to indicate that the client wants to close the connection to the directory server.\n\nExample:\n\n```ts\nawait client.unbind();\n```\n\n## Usage Examples\n\n### Authenticate example\n\n```ts\nconst { Client } = require('ldapts');\n\nconst url = 'ldap://ldap.forumsys.com:389';\nconst bindDN = 'cn=read-only-admin,dc=example,dc=com';\nconst password = 'password';\n\nconst client = new Client({\n  url,\n});\n\nlet isAuthenticated;\ntry {\n  await client.bind(bindDN, password);\n  isAuthenticated = true;\n} catch (ex) {\n  isAuthenticated = false;\n} finally {\n  await client.unbind();\n}\n```\n\n### Search example\n\n```ts\nconst { Client } = require('ldapts');\n\nconst url = 'ldaps://ldap.jumpcloud.com';\nconst bindDN = 'uid=tony.stark,ou=Users,o=5be4c382c583e54de6a3ff52,dc=jumpcloud,dc=com';\nconst password = 'MyRedSuitKeepsMeWarm';\nconst searchDN = 'ou=Users,o=5be4c382c583e54de6a3ff52,dc=jumpcloud,dc=com';\n\nconst client = new Client({\n  url,\n  tlsOptions: {\n    rejectUnauthorized: args.rejectUnauthorized,\n  },\n});\n\ntry {\n  await client.bind(bindDN, password);\n\n  const { searchEntries, searchReferences } = await client.search(searchDN, {\n    scope: 'sub',\n    filter: '(mail=peter.parker@marvel.com)',\n  });\n} catch (ex) {\n  throw ex;\n} finally {\n  await client.unbind();\n}\n```\n\n### Delete Active Directory entry example\n\n```ts\nconst { Client } = require('ldapts');\n\nconst url = 'ldap://127.0.0.1:1389';\nconst bindDN = 'uid=foo,dc=example,dc=com';\nconst password = 'bar';\nconst dnToDelete = 'uid=foobar,dc=example,dc=com';\n\nconst client = new Client({\n  url,\n});\n\ntry {\n  await client.bind(bindDN, password);\n\n  await client.del(dnToDelete);\n} catch (ex) {\n  if (ex instanceof InvalidCredentialsError) {\n    // Handle authentication specifically\n  }\n\n  throw ex;\n} finally {\n  await client.unbind();\n}\n```\n\n## `using` declaration with Typescript\n\nFor more details look have a look at [using Declarations and Explicit Resource Management](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html)\n\n```ts\n{\n  await using client = new Client({\n    url: 'ldap://127.0.0.1:1389',\n  });\n  await client.bind(bindDN, password);\n}\n// unbind is called\n```\n\n## Configuring Secure Connections\n\nWhen configuring secure connections in `ldapts`, it is important to choose the appropriate TLS method (via the `Client` constructor or `client.startTLS`) based\non your LDAP server's requirements. Prefer connecting securely from the Client constructor if the server supports LDAP over SSL. If that's not available but the\nconnection can be upgraded to a secure connection, then connect insecurely and call startTLS to upgrade the connection to be secure.\n\n### Use `Client` Constructor for LDAPS\n\nIf the LDAP server requires `ldaps://` (LDAP over SSL), specify `ldaps://` in the `url` and provide `tlsOptions` to the Client constructor to handle certificate validation.\nThis will establish a secure connection to the LDAP server over TLS from the moment the LDAP client is instantiated.\n\nExample:\n\n```ts\nimport { Client } from 'ldapts';\nimport fs from 'fs';\nconst client = new Client({\n  url: 'ldaps://ldap.example.com',\n  tlsOptions: {\n    ca: [fs.readFileSync('/path/to/ca-cert.pem')],\n  },\n});\n```\n\n### Use `client.startTLS` for STARTTLS\n\nIf the server is unable to support LDAP over SSL but supports `STARTTLS`, the connection can be upgraded to a secure connection.\nConnect to the server using `ldap://` and call `client.startTLS()` to upgrade to a secure connection.\n\nExample:\n\n```ts\nimport { Client } from 'ldapts';\nimport fs from 'fs';\nconst client = new Client({ url: 'ldap://ldap.example.com' });\nasync function connectWithStartTLS() {\n  await client.startTLS({\n    ca: [fs.readFileSync('/path/to/ca-cert.pem')],\n  });\n}\n```\n\n## Common Errors\n\n### Client network socket disconnected before secure TLS connection was established\n\nCause: There is a mismatch between the LDAP protocol being used by the client and server. For example,\nThe server expects an `ldaps://` connection, but the client uses `ldap://` without upgrading to TLS.\nAlternatively, the client is configured to use LDAP over SSL, but is connecting to the server using the `ldap://` protocol.\n\nSolution: Review the configuration options above and ensure that the client and server are configured to use the same protocol.\nIf connecting to a `ldap://` address, call `startTLS()` to upgrade the connection. If connecting to an `ldaps://` protocol,\nprovide the TLS options in the `Client` constructor.\n\n### UNABLE_TO_VERIFY_LEAF_SIGNATURE\n\nCause: The LDAP server's certificate is untrusted, often due to a self-signed certificate or an incomplete certificate chain.\n\nSolution(s):\n\n- Provide the CA certificate to establish trust:\n\n  ```ts\n  import fs from 'fs';\n\n  const client = new Client({\n    url: 'ldaps://ldap.example.com',\n    tlsOptions: {\n      ca: [fs.readFileSync('/path/to/ca-cert.pem')],\n    },\n  });\n  ```\n\n- Allow self-signed certificates (not recommended for production):\n\n  ```ts\n  const client = new Client({\n    url: 'ldaps://ldap.example.com',\n    tlsOptions: {\n      rejectUnauthorized: false, // Allow untrusted certificates\n    },\n  });\n  ```\n\n### ECONNREFUSED\n\nCause: The LDAP server is not reachable at the specified host and port, or the server is not listening on the expected protocol.\n\nSolution:\n\n- Verify the server address, port, and protocol in the `url`.\n- Ensure the server is running and accessible.\n- Check firewall rules to allow connections on the required port (636 for `ldaps`, 389 for `ldap`).\n\n### Handshake inactivity timeout\n\nCause: The server takes too long to respond to the TLS handshake due to network latency or misconfiguration.\n\nSolution:\n\n- Check the LDAP server's performance.\n- Verify TLS configuration (e.g., ciphers and protocols) on both client and server.\n- Increase the timeout if necessary:\n\n  ```ts\n  const client = new Client({\n    url: 'ldaps://ldap.example.com',\n    timeout: 30000, // 30 seconds\n  });\n  ```\n\n### Self signed certificate in certificate chain\n\nCause: The server uses a certificate signed by an untrusted CA.\n\nSolution: Provide the CA certificate:\n\n```ts\nimport fs from 'fs';\n\nconst client = new Client({\n  url: 'ldaps://ldap.example.com',\n  tlsOptions: {\n    ca: [fs.readFileSync('/path/to/ca-cert.pem')],\n  },\n});\n```\n\n### DEPTH_ZERO_SELF_SIGNED_CERT\n\nCause: The LDAP server is using a self-signed certificate without an intermediate CA.\n\nSolution(s):\n\n- Use the server's certificate as the trusted CA:\n\n  ```ts\n  import fs from 'fs';\n\n  const client = new Client({\n    url: 'ldaps://ldap.example.com',\n    tlsOptions: {\n      ca: [fs.readFileSync('/path/to/server-cert.pem')],\n    },\n  });\n  ```\n\n- Allow self-signed certificates (not recommended for production):\n\n  ```ts\n  const client = new Client({\n    url: 'ldaps://ldap.example.com',\n    tlsOptions: {\n      rejectUnauthorized: false, // Allow self-signed certificates\n    },\n  });\n  ```\n\n## Development\n\n### Generate certificates\n\nRun [generate-certs.js](tests/data/generate-certs.mjs)\n\n```sh\nnode tests/data/generate-certs.mjs\n```\n\n### Start test OpenLDAP server\n\n```shell\ndocker compose up -d\n```\n\n### Close test OpenLDAP server\n\n```shell\ndocker compose down\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fldapts%2Fldapts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fldapts%2Fldapts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fldapts%2Fldapts/lists"}