ldapts
Advanced tools
Comparing version 3.0.4 to 3.0.5
363
CHANGELOG.md
@@ -1,235 +0,278 @@ | ||
| ### 3.0.4 | ||
| * Fix relative path in source maps. Fixes #102. Thanks @stevenhair! | ||
| # Change Log | ||
| ### 3.0.3 | ||
| * Update npms | ||
| ## 3.0.5 | ||
| ### 3.0.2 | ||
| * Update npms | ||
| - Add documentation for `explicitBufferAttributes` | ||
| - Format and lint markdown files | ||
| ### 3.0.1 | ||
| * Fix "Unhandled promise rejection" when calling modify without password. Fix #88. Thanks @ctaschereau! | ||
| * Enable typescript lint checks: [`noPropertyAccessFromIndexSignature`](https://www.typescriptlang.org/tsconfig#noPropertyAccessFromIndexSignature) and [`noImplicitOverride`](https://www.typescriptlang.org/tsconfig#noImplicitOverride) | ||
| * Update npms | ||
| ## 3.0.4 | ||
| ### 3.0.0 | ||
| * Drop Node.js 10 support | ||
| * Add Node.js v16 to CI tests | ||
| * Update npms | ||
| * Allow `timeLimit: 0` in search options. Fix #97. Thanks @liudonghua123! | ||
| - Fix relative path in source maps. Fixes #102. Thanks @stevenhair! | ||
| ### 2.12.0 | ||
| * Export error classes. Fix #93 | ||
| * Redact password field from debug logging during send(). Fix #94 | ||
| * Update npms | ||
| * Enable package-lock.json to speed up CI builds | ||
| ## 3.0.3 | ||
| ### 2.11.1 | ||
| * Update npms | ||
| - Update npms | ||
| ### 2.11.0 | ||
| * Update npms | ||
| * Sort union/intersection members | ||
| * Revert remove sequence identifier for SASL authentication | ||
| ## 3.0.2 | ||
| ### 2.10.1 | ||
| * Update npms | ||
| * Fix documentation for SASL authentication | ||
| * Remove sequence identifier for SASL authentication | ||
| - Update npms | ||
| ### 2.10.0 | ||
| * Add support for PLAIN and EXTERNAL SASL authentication to bind request | ||
| ## 3.0.1 | ||
| ### 2.9.1 | ||
| * Simplify control import directives | ||
| - Fix "Unhandled promise rejection" when calling modify without password. Fix #88. Thanks @ctaschereau! | ||
| - Enable typescript lint checks: [`noPropertyAccessFromIndexSignature`](https://www.typescriptlang.org/tsconfig#noPropertyAccessFromIndexSignature) and [`noImplicitOverride`](https://www.typescriptlang.org/tsconfig#noImplicitOverride) | ||
| - Update npms | ||
| ### 2.9.0 | ||
| * Update npms | ||
| * Improve Control usability and provide example test for search with a custom Control. Fix #91 | ||
| ## 3.0.0 | ||
| ### 2.8.1 | ||
| * Fix null/undefined values for attributes when calling add(). Fix #88 | ||
| - Drop Node.js 10 support | ||
| - Add Node.js v16 to CI tests | ||
| - Update npms | ||
| - Allow `timeLimit: 0` in search options. Fix #97. Thanks @liudonghua123! | ||
| ### 2.8.0 | ||
| * Fix modifyDN to ignore escaped commas when determining NewSuperior. PR #87 Thanks @hasegawa-jun! | ||
| * Add tests for modifyDN | ||
| * Update npms | ||
| * Format code with prettier | ||
| ## 2.12.0 | ||
| ### 2.7.0 | ||
| * Support NewSuperior with modifyDN. PR #84 Thanks @IsraelFrid! | ||
| * Update npms | ||
| - Export error classes. Fix #93 | ||
| - Redact password field from debug logging during send(). Fix #94 | ||
| - Update npms | ||
| - Enable package-lock.json to speed up CI builds | ||
| ### 2.6.1 | ||
| * Added documentation for `explicitBufferAttributes` attribute | ||
| ## 2.11.1 | ||
| ### 2.6.0 | ||
| * Update npms | ||
| * Expose parsedBuffers on Attribute and added `explicitBufferAttributes` to search options. Fix #72 and Fix #82 | ||
| - Update npms | ||
| ### 2.5.1 | ||
| * Update npms | ||
| ## 2.11.0 | ||
| ### 2.5.0 | ||
| * Update @types/node npm to latest version. Fix #73 | ||
| * Add mocharc file | ||
| - Update npms | ||
| - Sort union/intersection members | ||
| - Revert remove sequence identifier for SASL authentication | ||
| ### 2.4.0 | ||
| * Add Buffer as value type for client.exop(). Fixes #74 | ||
| ## 2.10.1 | ||
| ### 2.3.0 | ||
| * Update npms | ||
| * Update Typescript to v3.9 | ||
| - Update npms | ||
| - Fix documentation for SASL authentication | ||
| - Remove sequence identifier for SASL authentication | ||
| ### 2.2.1 | ||
| * Update npms | ||
| ## 2.10.0 | ||
| ### 2.2.0 | ||
| * Support `startTLS` for upgrading an existing connection to be encrypted. Fix #71 | ||
| * Fix type of `tlsOptions` to `tls.ConnectionOptions` in `Client` constructor options | ||
| * Fix sending exop with empty/undefined value | ||
| * Add `.id` to internal socket to allow cleanup when unbinding after startTLS | ||
| - Add support for PLAIN and EXTERNAL SASL authentication to bind request | ||
| ### 2.1.0 | ||
| * Use secure connection if `tlsOptions` is specified or if url starts with `ldaps:` when constructing a client. Fix #71 | ||
| ## 2.9.1 | ||
| ### 2.0.3 | ||
| * Update npms | ||
| * Make typescript lint rules more strict | ||
| - Simplify control import directives | ||
| ### 2.0.2 | ||
| * Ignore case when determining if attribute is binary. Fix #11 | ||
| ## 2.9.0 | ||
| ### 2.0.1 | ||
| * Documentation updates | ||
| - Update npms | ||
| - Improve Control usability and provide example test for search with a custom Control. Fix #91 | ||
| ### 2.0.0 | ||
| * Drop support for nodejs v8 | ||
| * Update to Typescript 3.7 | ||
| * Fix exop response overwriting status and error message. Fixes #52 | ||
| * Update npms | ||
| * Improve documentation. Lots of :heart: for ldapjs docs, [ldapwiki](https://ldapwiki.com/), and [ldap.com](https://ldap.com/ldapv3-wire-protocol-reference/) docs. Fix #31 | ||
| ## 2.8.1 | ||
| ### 1.10.0 | ||
| * Include original error message with exceptions. Fix #36 | ||
| * Include all requested attributes with search results. Fix #22 | ||
| * Add isConnected to Client. Fix #25 | ||
| * Try to fix socket ending and reference handling issues. Thanks @december1981! Fix #24 | ||
| * Update npms | ||
| - Fix null/undefined values for attributes when calling add(). Fix #88 | ||
| ### 1.9.0 | ||
| * Export Change and Attribute classes. Thanks @willmcenaney! | ||
| * Parse search filter before sending partial request. Thanks @markhatchell! | ||
| ## 2.8.0 | ||
| ### 1.8.0 | ||
| * Remove "dist" folder from published npm | ||
| * Include type definitions as "dependencies" instead of "devDependencies" | ||
| * Update npms | ||
| - Fix modifyDN to ignore escaped commas when determining NewSuperior. PR #87 Thanks @hasegawa-jun! | ||
| - Add tests for modifyDN | ||
| - Update npms | ||
| - Format code with prettier | ||
| ### 1.7.0 | ||
| * Add DN class as alternate option for specifying DNs. Thanks @adrianplavka! | ||
| * Update npms | ||
| ## 2.7.0 | ||
| ### 1.6.0 | ||
| * Fix incorrectly escaping search filter names/values. Fix #18 | ||
| - Support NewSuperior with modifyDN. PR #84 Thanks @IsraelFrid! | ||
| - Update npms | ||
| ### 1.5.1 | ||
| * Do not throw "Size limit exceeded" error if `sizeLimit` is defined and the server responds with `4` (Size limit exceeded). | ||
| - Note: It seems that items are returned even though the return status is `4` (Size limit exceeded). | ||
| ## 2.6.1 | ||
| I'm not really sure what to do in that case. At this time, I decided against throwing an error and instead | ||
| just returning the results returned thus far. That approach works with JumpCloud and forumsys' ldap servers | ||
| - Added documentation for `explicitBufferAttributes` attribute | ||
| ### 1.5.0 | ||
| * Update dependencies | ||
| * Only include PagedResultsControl if `searchOptions.paged` is specified. Fixes #17 | ||
| * Make Filter.escape() public. Thanks @stiller-leser! | ||
| * Fix FilterParser parsing of ExtensibleFilters to include attribute type. Hopefully fixes #16 | ||
| ## 2.6.0 | ||
| ### 1.4.2 | ||
| - Update npms | ||
| - Expose parsedBuffers on Attribute and added `explicitBufferAttributes` to search options. Fix #72 and Fix #82 | ||
| * Update dependencies | ||
| * Add documentation for search options | ||
| ## 2.5.1 | ||
| ### 1.4.1 | ||
| - Update npms | ||
| * Fix 'Socket connection not established' when server closes the connection (Fix #13). Thanks @trevh3! | ||
| ## 2.5.0 | ||
| ### 1.4.0 | ||
| - Update @types/node npm to latest version. Fix #73 | ||
| - Add mocharc file | ||
| * Support binary attribute values (Fix #11) | ||
| ## 2.4.0 | ||
| ### 1.3.0 | ||
| - Add Buffer as value type for client.exop(). Fixes #74 | ||
| * Add Entry interface for SearchEntry. Thanks @hikaru7719! | ||
| ## 2.3.0 | ||
| ### 1.2.3 | ||
| - Update npms | ||
| - Update Typescript to v3.9 | ||
| * Move asn1 type definitions to DefinitelyTyped | ||
| ## 2.2.1 | ||
| ### 1.2.2 | ||
| - Update npms | ||
| * Fix error message for InvalidCredentialsError | ||
| ## 2.2.0 | ||
| ### 1.2.1 | ||
| - Support `startTLS` for upgrading an existing connection to be encrypted. Fix #71 | ||
| - Fix type of `tlsOptions` to `tls.ConnectionOptions` in `Client` constructor options | ||
| - Fix sending exop with empty/undefined value | ||
| - Add `.id` to internal socket to allow cleanup when unbinding after startTLS | ||
| * Provide exports for public classes: errors, filters, and messages (Fix #4) | ||
| ## 2.1.0 | ||
| ### 1.2.0 | ||
| - Use secure connection if `tlsOptions` is specified or if url starts with `ldaps:` when constructing a client. Fix #71 | ||
| * Fix escaping filter attribute names and values | ||
| ## 2.0.3 | ||
| ### 1.1.4 | ||
| - Update npms | ||
| - Make typescript lint rules more strict | ||
| * Fix Add and Modify to handle the response from the server. Thanks @adrianplavka! | ||
| ## 2.0.2 | ||
| ### 1.1.3 | ||
| - Ignore case when determining if attribute is binary. Fix #11 | ||
| * Update dev dependencies | ||
| ## 2.0.1 | ||
| ### 1.1.2 | ||
| - Documentation updates | ||
| * Fix ECONNRESET issue connecting to non-secure endpoint | ||
| * Throw an error for each message on socket error | ||
| ## 2.0.0 | ||
| ### 1.1.1 | ||
| - Drop support for nodejs v8 | ||
| - Update to Typescript 3.7 | ||
| - Fix exop response overwriting status and error message. Fixes #52 | ||
| - Update npms | ||
| - Improve documentation. Lots of :heart: for ldapjs docs, [ldapwiki](https://ldapwiki.com/), and [ldap.com](https://ldap.com/ldapv3-wire-protocol-reference/) docs. Fix #31 | ||
| * Add original string to error message when parsing filters | ||
| * Adjust parsing & and | in filters | ||
| * Add more filter parsing tests | ||
| ## 1.10.0 | ||
| ### 1.1.0 | ||
| - Include original error message with exceptions. Fix #36 | ||
| - Include all requested attributes with search results. Fix #22 | ||
| - Add isConnected to Client. Fix #25 | ||
| - Try to fix socket ending and reference handling issues. Thanks @december1981! Fix #24 | ||
| - Update npms | ||
| * Add client.add() and client.modify() | ||
| ## 1.9.0 | ||
| ### 1.0.6 | ||
| - Export Change and Attribute classes. Thanks @willmcenaney! | ||
| - Parse search filter before sending partial request. Thanks @markhatchell! | ||
| * Use hex for message type code in closed message error message | ||
| * Add additional test for calling unbind() multiple times | ||
| ## 1.8.0 | ||
| ### 1.0.5 | ||
| - Remove "dist" folder from published npm | ||
| - Include type definitions as "dependencies" instead of "devDependencies" | ||
| - Update npms | ||
| * Add message name to error message when socket is closed before message response | ||
| ## 1.7.0 | ||
| ### 1.0.4 | ||
| - Add DN class as alternate option for specifying DNs. Thanks @adrianplavka! | ||
| - Update npms | ||
| * Add type definitions for asn1 | ||
| * Add message type id to error when cleaning pending messages. | ||
| * Force protocolOperation to be defined for Message types | ||
| ## 1.6.0 | ||
| ### 1.0.3 | ||
| - Fix incorrectly escaping search filter names/values. Fix #18 | ||
| * Verify the socket exists before sending unbind message | ||
| ## 1.5.1 | ||
| ### 1.0.2 | ||
| - Do not throw "Size limit exceeded" error if `sizeLimit` is defined and the server responds with `4` (Size limit exceeded). | ||
| * Setup prepublish to always build. | ||
| * Push fix from 1.0.1 | ||
| - Note: It seems that items are returned even though the return status is `4` (Size limit exceeded). | ||
| ### 1.0.1 | ||
| I'm not really sure what to do in that case. At this time, I decided against throwing an error and instead | ||
| just returning the results returned thus far. That approach works with JumpCloud and forumsys' ldap servers | ||
| * Fix search to return attribute values by default | ||
| ## 1.5.0 | ||
| ### 1.0.0 | ||
| - Update dependencies | ||
| - Only include PagedResultsControl if `searchOptions.paged` is specified. Fixes #17 | ||
| - Make Filter.escape() public. Thanks @stiller-leser! | ||
| - Fix FilterParser parsing of ExtensibleFilters to include attribute type. Hopefully fixes #16 | ||
| * Initial release | ||
| ## 1.4.2 | ||
| - Update dependencies | ||
| - Add documentation for search options | ||
| ## 1.4.1 | ||
| - Fix 'Socket connection not established' when server closes the connection (Fix #13). Thanks @trevh3! | ||
| ## 1.4.0 | ||
| - Support binary attribute values (Fix #11) | ||
| ## 1.3.0 | ||
| - Add Entry interface for SearchEntry. Thanks @hikaru7719! | ||
| ## 1.2.3 | ||
| - Move asn1 type definitions to DefinitelyTyped | ||
| ## 1.2.2 | ||
| - Fix error message for InvalidCredentialsError | ||
| ## 1.2.1 | ||
| - Provide exports for public classes: errors, filters, and messages (Fix #4) | ||
| ## 1.2.0 | ||
| - Fix escaping filter attribute names and values | ||
| ## 1.1.4 | ||
| - Fix Add and Modify to handle the response from the server. Thanks @adrianplavka! | ||
| ## 1.1.3 | ||
| - Update dev dependencies | ||
| ## 1.1.2 | ||
| - Fix ECONNRESET issue connecting to non-secure endpoint | ||
| - Throw an error for each message on socket error | ||
| ## 1.1.1 | ||
| - Add original string to error message when parsing filters | ||
| - Adjust parsing & and | in filters | ||
| - Add more filter parsing tests | ||
| ## 1.1.0 | ||
| - Add client.add() and client.modify() | ||
| ## 1.0.6 | ||
| - Use hex for message type code in closed message error message | ||
| - Add additional test for calling unbind() multiple times | ||
| ## 1.0.5 | ||
| - Add message name to error message when socket is closed before message response | ||
| ## 1.0.4 | ||
| - Add type definitions for asn1 | ||
| - Add message type id to error when cleaning pending messages. | ||
| - Force protocolOperation to be defined for Message types | ||
| ## 1.0.3 | ||
| - Verify the socket exists before sending unbind message | ||
| ## 1.0.2 | ||
| - Setup prepublish to always build. | ||
| - Push fix from 1.0.1 | ||
| ## 1.0.1 | ||
| - Fix search to return attribute values by default | ||
| ## 1.0.0 | ||
| - Initial release |
| { | ||
| "name": "ldapts", | ||
| "version": "3.0.4", | ||
| "version": "3.0.5", | ||
| "description": "LDAP client", | ||
@@ -10,3 +10,5 @@ "main": "index.js", | ||
| "test": "mocha \"tests/**/*.tests.ts\"", | ||
| "lint": "eslint --fix --ext .ts src tests", | ||
| "lint:markdown": "prettier --write '*.md' '!(node_modules|dist)/**/*.md' && markdownlint '*.md' '!(node_modules|dist)/**/*.md' --config=.github/linters/.markdown-lint.yml --fix", | ||
| "lint:code": "eslint --fix --ext .ts src tests", | ||
| "lint": "run-p lint:*", | ||
| "lint-staged": "lint-staged", | ||
@@ -19,2 +21,5 @@ "dist": "if [ -d \"src\" ]; then rm -rf dist && npm run lint && npm run build && npm run test && cp package.json dist && cp package-lock.json dist && cp *.md dist && cp .npmignore dist && cd dist && npm publish; fi", | ||
| "lint-staged": { | ||
| "*.md": [ | ||
| "markdownlint --config=.github/linters/.markdown-lint.yml --fix" | ||
| ], | ||
| "*.js": [ | ||
@@ -76,3 +81,5 @@ "eslint --fix" | ||
| "lint-staged": "~11.0.1", | ||
| "markdownlint-cli": "~0.28.1", | ||
| "mocha": "~9.0.2", | ||
| "npm-run-all": "~4.1.5", | ||
| "pinst": "~2.1.6", | ||
@@ -79,0 +86,0 @@ "prettier": "~2.3.2", |
450
README.md
@@ -1,3 +0,2 @@ | ||
| LDAPts | ||
| ====== | ||
| # LDAPts | ||
@@ -10,29 +9,32 @@ [](https://npmjs.org/package/ldapts) | ||
| ### Table of Contents | ||
| * [API Details](#api-details) | ||
| * [Create a client](#create-a-client) | ||
| * [Specifying Controls](#specifying-controls) | ||
| * [bind](#bind) | ||
| * [startTLS](#startTLS) | ||
| * [add](#add) | ||
| * [compare](#compare) | ||
| * [del](#del) | ||
| * [exop](#exop) | ||
| * [modify](#modify) | ||
| * [Change](#change) | ||
| * [modifyDN](#modifydn) | ||
| * [search](#search) | ||
| * [Filter Strings](#filter-strings) | ||
| * [unbind](#unbind) | ||
| * [Usage Examples](#usage-examples) | ||
| * [Authenticate example](#authenticate-example) | ||
| * [Search example](#search-example) | ||
| * [Delete Active Directory entry example](#delete-active-directory-entry-example) | ||
| ## Table of Contents | ||
| # API details | ||
| ## Create a client | ||
| - [API Details](#api-details) | ||
| - [Create a client](#create-a-client) | ||
| - [Specifying Controls](#specifying-controls) | ||
| - [bind](#bind) | ||
| - [startTLS](#startTLS) | ||
| - [add](#add) | ||
| - [compare](#compare) | ||
| - [del](#del) | ||
| - [exop](#exop) | ||
| - [modify](#modify) | ||
| - [Change](#change) | ||
| - [modifyDN](#modifydn) | ||
| - [search](#search) | ||
| - [Filter Strings](#filter-strings) | ||
| - [Return buffer for specific attribute](#return-buffer-for-specific-attribute) | ||
| - [unbind](#unbind) | ||
| - [Usage Examples](#usage-examples) | ||
| - [Authenticate example](#authenticate-example) | ||
| - [Search example](#search-example) | ||
| - [Delete Active Directory entry example](#delete-active-directory-entry-example) | ||
| ## API details | ||
| ### Create a client | ||
| The code to create a new client looks like: | ||
| ```javascript | ||
| ```ts | ||
| import { Client } from 'ldapts'; | ||
@@ -56,11 +58,11 @@ | ||
| |Attribute |Description | | ||
| |---------------|-----------------------------------------------------------| | ||
| |url |A valid LDAP URL (proto/host/port only) | | ||
| |timeout |Milliseconds client should let operations live for before timing out (Default: Infinity)| | ||
| |connectTimeout |Milliseconds client should wait before timing out on TCP connections (Default: OS default)| | ||
| |tlsOptions |TLS [connect() options](https://nodejs.org/api/tls.html#tls_tls_connect_options_callback)| | ||
| |strictDN |Force strict DN parsing for client methods (Default is true)| | ||
| | Attribute | Description | | ||
| | -------------- | ------------------------------------------------------------------------------------------ | | ||
| | url | A valid LDAP URL (proto/host/port only) | | ||
| | timeout | Milliseconds client should let operations live for before timing out (Default: Infinity) | | ||
| | connectTimeout | Milliseconds client should wait before timing out on TCP connections (Default: OS default) | | ||
| | tlsOptions | TLS [connect() options](https://nodejs.org/api/tls.html#tls_tls_connect_options_callback) | | ||
| | strictDN | Force strict DN parsing for client methods (Default is true) | | ||
| ## Specifying Controls | ||
| ### Specifying Controls | ||
@@ -72,8 +74,9 @@ Single or an array of `Control` objects can be added to various operations like the following: | ||
| const { | ||
| searchEntries, | ||
| searchReferences, | ||
| } = await client.search(searchDN, { | ||
| filter: '(mail=peter.parker@marvel.com)', | ||
| }, new Control('1.2.840.113556.1.4.417')); | ||
| const { searchEntries, searchReferences } = await client.search( | ||
| searchDN, | ||
| { | ||
| filter: '(mail=peter.parker@marvel.com)', | ||
| }, | ||
| new Control('1.2.840.113556.1.4.417'), | ||
| ); | ||
| ``` | ||
@@ -84,3 +87,4 @@ | ||
| ## bind | ||
| ### bind | ||
| `bind(dn, password, [controls])` | ||
@@ -96,22 +100,27 @@ | ||
| |Argument |Description | ||
| |---------|-------------- | ||
| |`dnOrSaslMechanism` (string)|The name (DN) of the directory object that the client wishes to bind as or the SASL mechanism (PLAIN, EXTERNAL) | ||
| |`[password]` (string)|Password for the target bind DN | ||
| |`[controls]` (Control|Control[])|Optional `Control` object or array of `Control` objects | ||
| | Argument | Description | | ||
| | ------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | ||
| | `dnOrSaslMechanism` (string) | The name (DN) of the directory object that the client wishes to bind as or the SASL mechanism (PLAIN, EXTERNAL) | | ||
| | `[password]` (string) | Password for the target bind DN | | ||
| | `[controls]` (Control|Control[]) | Optional `Control` object or array of `Control` objects | | ||
| Simple Example: | ||
| await client.bind('cn=root', 'secret'); | ||
| ```ts | ||
| await client.bind('cn=root', 'secret'); | ||
| ``` | ||
| SASL Example: | ||
| // No credentials | ||
| await client.bind("EXTERNAL"); | ||
| ```ts | ||
| // No credentials | ||
| await client.bind('EXTERNAL'); | ||
| // With credentials | ||
| const credentials = '...foo...'; | ||
| await client.bind("PLAIN", credentials); | ||
| // With credentials | ||
| const credentials = '...foo...'; | ||
| await client.bind('PLAIN', credentials); | ||
| ``` | ||
| ## startTLS | ||
| ### startTLS | ||
| `startTLS(options, [controls])` | ||
@@ -124,14 +133,17 @@ | ||
| |Argument |Description | ||
| |---------|-------------- | ||
| |`options` (object)|TLS [connect() options](https://nodejs.org/api/tls.html#tls_tls_connect_options_callback) | ||
| |`[controls]` (Control|Control[])|Optional `Control` object or array of `Control` objects | ||
| | Argument | Description | | ||
| | ------------------------------------- | ----------------------------------------------------------------------------------------- | | ||
| | `options` (object) | TLS [connect() options](https://nodejs.org/api/tls.html#tls_tls_connect_options_callback) | | ||
| | `[controls]` (Control|Control[]) | Optional `Control` object or array of `Control` objects | | ||
| Example: | ||
| await client.startTLS({ | ||
| ca: [fs.readFileSync('mycacert.pem')], | ||
| }); | ||
| ```ts | ||
| await client.startTLS({ | ||
| ca: [fs.readFileSync('mycacert.pem')], | ||
| }); | ||
| ``` | ||
| ## add | ||
| ### add | ||
| `add(dn, entry, [controls])` | ||
@@ -146,19 +158,22 @@ | ||
| |Argument |Description | ||
| |---------|-------------- | ||
| |`dn` (string)|The DN of the entry to add | ||
| |`entry` (object|Attribute[])|The set of attributes to include in that entry | ||
| |`[controls]` (Control|Control[])|Optional `Control` object or array of `Control` objects | ||
| | Argument | Description | | ||
| | ------------------------------------- | ------------------------------------------------------- | | ||
| | `dn` (string) | The DN of the entry to add | | ||
| | `entry` (object|Attribute[]) | The set of attributes to include in that entry | | ||
| | `[controls]` (Control|Control[]) | Optional `Control` object or array of `Control` objects | | ||
| Example: | ||
| var entry = { | ||
| cn: 'foo', | ||
| sn: 'bar', | ||
| email: ['foo@bar.com', 'foo1@bar.com'], | ||
| objectclass: 'fooPerson' | ||
| }; | ||
| await client.add('cn=foo, o=example', entry); | ||
| ```ts | ||
| var entry = { | ||
| cn: 'foo', | ||
| sn: 'bar', | ||
| email: ['foo@bar.com', 'foo1@bar.com'], | ||
| objectclass: 'fooPerson', | ||
| }; | ||
| await client.add('cn=foo, o=example', entry); | ||
| ``` | ||
| ## compare | ||
| ### compare | ||
| `compare(dn, attribute, value, [controls])` | ||
@@ -171,17 +186,20 @@ | ||
| |Argument |Description | ||
| |---------|-------------- | ||
| |`dn` (string)|The DN of the entry in which the comparison is to be made | ||
| |`attribute` (string)|The Name of the attribute in which the comparison is to be made | ||
| |`value` (string)|The Attribute Value Assertion to try to find in the specified attribute | ||
| |`[controls]` (Control|Control[])|Optional `Control` object or array of `Control` objects | ||
| | Argument | Description | | ||
| | ------------------------------------- | ----------------------------------------------------------------------- | | ||
| | `dn` (string) | The DN of the entry in which the comparison is to be made | | ||
| | `attribute` (string) | The Name of the attribute in which the comparison is to be made | | ||
| | `value` (string) | The Attribute Value Assertion to try to find in the specified attribute | | ||
| | `[controls]` (Control|Control[]) | Optional `Control` object or array of `Control` objects | | ||
| Returns: | ||
| `(boolean)`: Returns `true` if the target entry exists and does contain the specified attribute value; otherwise `false` | ||
| `(boolean)`: Returns `true` if the target entry exists and does contain the specified attribute value; otherwise `false` | ||
| Example: | ||
| const hasValue = await client.compare('cn=foo, o=example', 'sn', 'bar'); | ||
| ```ts | ||
| const hasValue = await client.compare('cn=foo, o=example', 'sn', 'bar'); | ||
| ``` | ||
| ## del | ||
| ### del | ||
| `del(dn, [controls])` | ||
@@ -193,12 +211,15 @@ | ||
| |Argument |Description | ||
| |---------|-------------- | ||
| `dn` (string)|The DN of the entry to delete | ||
| `[controls]` (Control|Control[])|Optional `Control` object or array of `Control` objects | ||
| | Argument | Description | | ||
| | ------------------------------------- | ------------------------------------------------------- | | ||
| | `dn` (string) | The DN of the entry to delete | | ||
| | `[controls]` (Control|Control[]) | Optional `Control` object or array of `Control` objects | | ||
| Example: | ||
| await client.del('cn=foo, o=example'); | ||
| ```ts | ||
| await client.del('cn=foo, o=example'); | ||
| ``` | ||
| ## exop | ||
| ### exop | ||
| `exop(oid, [value], [controls])` | ||
@@ -210,18 +231,20 @@ | ||
| |Argument |Description | ||
| |---------|-------------- | ||
| |`oid` (string)|Object identifier representing the type of request | ||
| |`[value]` (string)|Optional value - based on the type of operation | ||
| |`[controls]` (Control|Control[])|Optional `Control` object or array of `Control` objects | ||
| | Argument | Description | | ||
| | ------------------------------------- | ------------------------------------------------------- | | ||
| | `oid` (string) | Object identifier representing the type of request | | ||
| | `[value]` (string) | Optional value - based on the type of operation | | ||
| | `[controls]` (Control|Control[]) | Optional `Control` object or array of `Control` objects | | ||
| Example (performs an LDAP 'whois' extended op): | ||
| const { value } = await client.exop('1.3.6.1.4.1.4203.1.11.3'); | ||
| ```ts | ||
| const { value } = await client.exop('1.3.6.1.4.1.4203.1.11.3'); | ||
| ``` | ||
| ## modify | ||
| ### modify | ||
| `modify(name, changes, [controls])` | ||
| Performs an LDAP modify operation against the LDAP server. This API requires | ||
| you to pass in a `Change` object, which is described below. Note that you can | ||
| Performs an LDAP modify operation against the LDAP server. This API requires | ||
| you to pass in a `Change` object, which is described below. Note that you can | ||
| pass in a single `Change` or an array of `Change` objects. | ||
@@ -231,36 +254,39 @@ | ||
| |Argument |Description | ||
| |---------|-------------- | ||
| `dn` (string)|The DN of the entry to modify | ||
| `changes` (Change|Change[])|The set of changes to make to the entry | ||
| `[controls]` (Control|Control[])|Optional `Control` object or array of `Control` objects | ||
| | Argument | Description | | ||
| | ------------------------------------- | ------------------------------------------------------- | | ||
| | `dn` (string) | The DN of the entry to modify | | ||
| | `changes` (Change|Change[]) | The set of changes to make to the entry | | ||
| | `[controls]` (Control|Control[]) | Optional `Control` object or array of `Control` objects | | ||
| Example (update multiple attributes): | ||
| import { Attribute, Change } from 'ldapts'; | ||
| ```ts | ||
| import { Attribute, Change } from 'ldapts'; | ||
| await client.modify('cn=foo, o=example', [ | ||
| new Change({ operation: 'replace', modification: new Attribute({ type: 'title', values: ['web tester'] })), | ||
| new Change({ operation: 'replace', modification: new Attribute({ type: 'displayName', values: ['John W Doe'] })), | ||
| ]); | ||
| await client.modify('cn=foo, o=example', [ | ||
| new Change({ operation: 'replace', modification: new Attribute({ type: 'title', values: ['web tester'] }) }), | ||
| new Change({ operation: 'replace', modification: new Attribute({ type: 'displayName', values: ['John W Doe'] }) }), | ||
| ]); | ||
| ``` | ||
| Example (update binary attribute): | ||
| import { Attribute, Change } from 'ldapts'; | ||
| ```ts | ||
| import { Attribute, Change } from 'ldapts'; | ||
| const thumbnailPhotoBuffer = await fs.readFile(path.join(__dirname, './groot_100.jpg')); | ||
| const thumbnailPhotoBuffer = await fs.readFile(path.join(__dirname, './groot_100.jpg')); | ||
| var change = new Change({ | ||
| operation: 'replace', | ||
| modification: new Attribute({ | ||
| type: 'thumbnailPhoto;binary', | ||
| values: [thumbnailPhotoBuffer] | ||
| }), | ||
| }); | ||
| var change = new Change({ | ||
| operation: 'replace', | ||
| modification: new Attribute({ | ||
| type: 'thumbnailPhoto;binary', | ||
| values: [thumbnailPhotoBuffer], | ||
| }), | ||
| }); | ||
| await client.modify('cn=foo, o=example', change); | ||
| await client.modify('cn=foo, o=example', change); | ||
| ``` | ||
| ### Change | ||
| #### Change | ||
| `Change({ operation, modification })` | ||
@@ -273,41 +299,48 @@ | ||
| |Argument |Description | ||
| |---------|-------------- | ||
| |`operation` (replace|add|delete)|*See table below* | ||
| |`modification` (Attribute)|Attribute details to add, remove, or update | ||
| | Argument | Description | | ||
| | ------------------------------------------ | ------------------------------------------- | | ||
| | `operation` (replace|add|delete) | _See table below_ | | ||
| | `modification` (Attribute) | Attribute details to add, remove, or update | | ||
| Operations: | ||
| | Value | Description | ||
| | --------- | ------------ | ||
| | `replace` |Replaces the attribute referenced in `modification`. If the modification has no values, it is equivalent to a delete.| | ||
| | `add` |Adds the attribute value(s) referenced in `modification`. The attribute may or may not already exist.| | ||
| | `delete` |Deletes the attribute (and all values) referenced in `modification`.| | ||
| | Value | Description | | ||
| | --------- | --------------------------------------------------------------------------------------------------------------------- | | ||
| | `replace` | Replaces the attribute referenced in `modification`. If the modification has no values, it is equivalent to a delete. | | ||
| | `add` | Adds the attribute value(s) referenced in `modification`. The attribute may or may not already exist. | | ||
| | `delete` | Deletes the attribute (and all values) referenced in `modification`. | | ||
| ## modifyDN | ||
| ### modifyDN | ||
| `modifyDN(dn, newDN, [controls])` | ||
| Performs an LDAP modifyDN (rename) operation against an entry in the LDAP | ||
| server. A couple points with this client API: | ||
| server. A couple points with this client API: | ||
| * There is no ability to set "keep old dn." It's always going to flag the old | ||
| dn to be purged. | ||
| * The client code will automatically figure out if the request is a "new | ||
| superior" request ("new superior" means move to a different part of the tree, | ||
| as opposed to just renaming the leaf). | ||
| - There is no ability to set "keep old dn." It's always going to flag the old | ||
| dn to be purged. | ||
| - The client code will automatically figure out if the request is a "new | ||
| superior" request ("new superior" means move to a different part of the tree, | ||
| as opposed to just renaming the leaf). | ||
| <!-- markdownlint-disable line-length --> | ||
| Arguments: | ||
| |Argument |Description | ||
| |---------|-------------- | ||
| |`dn` (string)|The DN of the entry to rename | ||
| |`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. | ||
| |`[controls]` (Control|Control[])|Optional `Control` object or array of `Control` objects | ||
| | Argument | Description | | ||
| | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | ||
| | `dn` (string) | The DN of the entry to rename | | ||
| | `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. | | ||
| | `[controls]` (Control|Control[]) | Optional `Control` object or array of `Control` objects | | ||
| <!-- markdownlint-enable line-length --> | ||
| Example: | ||
| await client.modifyDN('cn=foo, o=example', 'cn=bar'); | ||
| ```ts | ||
| await client.modifyDN('cn=foo, o=example', 'cn=bar'); | ||
| ``` | ||
| ## search | ||
| ### search | ||
| `search(baseDN, options, [controls])` | ||
@@ -322,36 +355,37 @@ | ||
| |Argument |Description | ||
| |---------|-------------- | ||
| |`baseDN` (string)|The base of the subtree in which the search is to be constrained | ||
| |`options` (object)|*See table below* | ||
| |`[controls]` (Control|Control[])|Optional `Control` object or array of `Control` objects | ||
| | Argument | Description | | ||
| | ------------------------------------- | ---------------------------------------------------------------- | | ||
| | `baseDN` (string) | The base of the subtree in which the search is to be constrained | | ||
| | `options` (object) | _See table below_ | | ||
| | `[controls]` (Control|Control[]) | Optional `Control` object or array of `Control` objects | | ||
| <!-- markdownlint-disable line-length no-inline-html --> | ||
| Options: | ||
| |Attribute |Description | ||
| |-----------------------------------------------|---------------------------------------------------| | ||
| |[scope=sub] (string) |<ul><li>`base` - Indicates that only the entry specified as the search base should be considered. None of its subordinates will be considered.</li><li>`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.</li><li>`sub` - Indicates that the entry specified as the search base, and all of its subordinates to any depth, should be considered.</li><li>`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.</li></ul> | ||
| |[filter=(objectclass=*)] (string|Filter) |The filter of the search request. It must conform to the LDAP filter syntax specified in RFC4515 | ||
| |[derefAliases=never] (string) |<ul><li>`never` - Never dereferences entries, returns alias objects instead. The alias contains the reference to the real entry.</li><li>`always` - Always returns the referenced entries, not the alias object.</li><li>`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.</li><li>`find` - Dereferences aliases in locating the base object of the search, but not when searching subordinates of the base object.</li></ul> | ||
| |[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. | ||
| |[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. | ||
| |[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. | ||
| |[paged=false] (boolean|SearchPageOptions) |Used to allow paging and specify the page size | ||
| |[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. | ||
| |[explicitBufferAttributes=] (string[]) |List of explicit attribute names to return as Buffer objects | ||
| | Attribute | Description | | ||
| | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | ||
| | [scope=sub] (string) | <ul><li>`base` - Indicates that only the entry specified as the search base should be considered. None of its subordinates will be considered.</li><li>`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.</li><li>`sub` - Indicates that the entry specified as the search base, and all of its subordinates to any depth, should be considered.</li><li>`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.</li></ul> | | ||
| | [filter=(objectclass=*)] (string|Filter) | The filter of the search request. It must conform to the LDAP filter syntax specified in RFC4515 | | ||
| | [derefAliases=never] (string) | <ul><li>`never` - Never dereferences entries, returns alias objects instead. The alias contains the reference to the real entry.</li><li>`always` - Always returns the referenced entries, not the alias object.</li><li>`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.</li><li>`find` - Dereferences aliases in locating the base object of the search, but not when searching subordinates of the base object.</li></ul> | | ||
| | [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. | | ||
| | [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. | | ||
| | [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. | | ||
| | [paged=false] (boolean|SearchPageOptions) | Used to allow paging and specify the page size | | ||
| | [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. | | ||
| | [explicitBufferAttributes=] (string[]) | List of explicit attribute names to return as Buffer objects | | ||
| <!-- markdownlint-enable line-length no-inline-html --> | ||
| Example: | ||
| const { | ||
| searchEntries, | ||
| searchReferences, | ||
| } = await client.search(searchDN, { | ||
| filter: '(mail=peter.parker@marvel.com)', | ||
| }); | ||
| ```ts | ||
| const { searchEntries, searchReferences } = await client.search(searchDN, { | ||
| filter: '(mail=peter.parker@marvel.com)', | ||
| }); | ||
| ``` | ||
| Please see [Client tests](https://github.com/ldapts/ldapts/blob/master/tests/Client.tests.ts) for more search examples | ||
| ### Filter Strings | ||
| #### Filter Strings | ||
@@ -363,7 +397,9 @@ The easiest way to write search filters is to write them compliant with RFC2254, | ||
| basically are a "tree" of attribute/value assertions, with the tree specified | ||
| in prefix notation. For example, let's start simple, and build up a complicated | ||
| filter. The most basic filter is equality, so let's assume you want to search | ||
| for an attribute `email` with a value of `foo@bar.com`. The syntax would be: | ||
| in prefix notation. For example, let's start simple, and build up a complicated | ||
| filter. The most basic filter is equality, so let's assume you want to search | ||
| for an attribute `email` with a value of `foo@bar.com`. The syntax would be: | ||
| (email=foo@bar.com) | ||
| ```ts | ||
| const filter = `(email=foo@bar.com)`; | ||
| ``` | ||
@@ -375,5 +411,7 @@ ldapts requires all filters to be surrounded by '()' blocks. Ok, that was easy. | ||
| (&(email=*@bar.com)(l=Seattle)) | ||
| ```ts | ||
| const filter = `(&(email=*@bar.com)(l=Seattle))`; | ||
| ``` | ||
| Now our filter is actually three LDAP filters. We have an `and` filter (single | ||
| Now our filter is actually three LDAP filters. We have an `and` filter (single | ||
| amp `&`), an `equality` filter `(the l=Seattle)`, and a `substring` filter. | ||
@@ -385,5 +423,7 @@ Substrings are wildcard filters. They use `*` as the wildcard. You can put more | ||
| Now, let's say we also want to set our filter to include a | ||
| specification that either the employeeType *not* be a manager nor a secretary: | ||
| specification that either the employeeType _not_ be a manager nor a secretary: | ||
| (&(email=*@bar.com)(l=Seattle)(!(|(employeeType=manager)(employeeType=secretary)))) | ||
| ```ts | ||
| const filter = `(&(email=*@bar.com)(l=Seattle)(!(|(employeeType=manager)(employeeType=secretary))))`; | ||
| ``` | ||
@@ -394,3 +434,29 @@ The `not` character is represented as a `!`, the `or` as a single pipe `|`. | ||
| ## unbind | ||
| #### Return buffer for specific attribute | ||
| Sometimes you may want to get a buffer back instead of a string for an attribute value. Depending on the server software, | ||
| you may be able to append `;binary` | ||
| (the [binary attribute subtype](https://docs.oracle.com/cd/E19424-01/820-4809/bcacz/index.html)) to the attribute name, | ||
| to have the value returned as a Buffer. | ||
| ```ts | ||
| const searchResults = await ldapClient.search('ou=Users,o=5be4c382c583e54de6a3ff52,dc=jumpcloud,dc=com', { | ||
| filter: '(mail=peter.parker@marvel.com)', | ||
| attributes: ['jpegPhoto;binary'], | ||
| }); | ||
| ``` | ||
| However, some servers are very strict when it comes to the binary attribute subtype and will only acknowledge it if | ||
| there is an associated AN.1 type or valid BER encoding. In those cases, you can tell ldapts to explicitly return a | ||
| Buffer for an attribute: | ||
| ```ts | ||
| const searchResult = await client.search('ou=Users,o=5be4c382c583e54de6a3ff52,dc=jumpcloud,dc=com', { | ||
| filter: '(mail=peter.parker@marvel.com)', | ||
| explicitBufferAttributes: ['jpegPhoto'], | ||
| }); | ||
| ``` | ||
| ### unbind | ||
| `unbind()` | ||
@@ -402,11 +468,11 @@ | ||
| await client.unbind(); | ||
| ```ts | ||
| await client.unbind(); | ||
| ``` | ||
| ## Usage Examples | ||
| ### Authenticate example | ||
| # Usage Examples | ||
| ## Authenticate example | ||
| ```javascript | ||
| ```ts | ||
| const { Client } = require('ldapts'); | ||
@@ -431,8 +497,7 @@ | ||
| } | ||
| ``` | ||
| ## Search example | ||
| ### Search example | ||
| ```javascript | ||
| ```ts | ||
| const { Client } = require('ldapts'); | ||
@@ -455,6 +520,3 @@ | ||
| const { | ||
| searchEntries, | ||
| searchReferences, | ||
| } = await client.search(searchDN, { | ||
| const { searchEntries, searchReferences } = await client.search(searchDN, { | ||
| scope: 'sub', | ||
@@ -468,8 +530,7 @@ filter: '(mail=peter.parker@marvel.com)', | ||
| } | ||
| ``` | ||
| ## Delete Active Directory entry example | ||
| ### Delete Active Directory entry example | ||
| ```javascript | ||
| ```ts | ||
| const { Client } = require('ldapts'); | ||
@@ -491,3 +552,3 @@ | ||
| } catch (ex) { | ||
| if (ex typeof InvalidCredentialsError) { | ||
| if (ex instanceof InvalidCredentialsError) { | ||
| // Handle authentication specifically | ||
@@ -500,3 +561,2 @@ } | ||
| } | ||
| ``` |
No alert changes
Improved metrics
- Total package byte prevSize
- increased by3.21%
351852
- Number of lines in readme file
- increased by12.5%
540
Worsened metrics
- Dev dependency count
- increased by7.14%
30
- Number of package files
- decreased by-0.34%
294
No dependency changes