forked from ldapjs/ldapjs.github.io
-
Notifications
You must be signed in to change notification settings - Fork 0
/
client.html
638 lines (621 loc) · 30 KB
/
client.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
<!DOCTYPE html>
<html lang="en">
<head>
<title>Client API | ldapjs</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link rel="stylesheet" type="text/css" href="media/css/style.css">
<link rel="stylesheet" type="text/css" href="media/css/highlight.css">
</head>
<body>
<div id="header">
<h1>Client API | ldapjs Documentation</h1>
</div>
<div id="sidebar">
<div>Sections</div>
<span>
<ul>
<li><div><a href="index.html">Home</a></div></li>
<li><div><a href="guide.html">Guide</a></div></li>
<li><div><a href="examples.html">Examples</a></div></li>
<li><div><a href="client.html">Client API</a></div></li>
<li><div><a href="server.html">Server API</a></div></li>
<li><div><a href="dn.html">DN API</a></div></li>
<li><div><a href="filters.html">Filters API</a></div></li>
<li><div><a href="errors.html">Error API</a></div></li>
</ul>
</span>
<div>Contents</div>
</span>
<ul>
<li>
<div>
<a href="#create-a-client">Create a client</a>
</div>
<ul>
<li>
<div>
<a href="#connection-management">Connection management</a>
</div>
</li>
<li>
<div>
<a href="#client-events">Client events</a>
</div>
</li>
<li>
<div>
<a href="#common-patterns">Common patterns</a>
</div>
</li>
</ul>
</li>
<li>
<div>
<a href="#bind">bind</a>
</div>
</li>
<li>
<div>
<a href="#add">add</a>
</div>
</li>
<li>
<div>
<a href="#compare">compare</a>
</div>
</li>
<li>
<div>
<a href="#del">del</a>
</div>
</li>
<li>
<div>
<a href="#exop">exop</a>
</div>
</li>
<li>
<div>
<a href="#modify">modify</a>
</div>
<ul>
<li>
<div>
<a href="#change">Change</a>
</div>
</li>
</ul>
</li>
<li>
<div>
<a href="#modifydn">modifyDN</a>
</div>
</li>
<li>
<div>
<a href="#search">search</a>
</div>
<ul>
<li>
<div>
<a href="#filter-strings">Filter Strings</a>
</div>
</li>
<li>
<div>
<a href="#paging">Paging</a>
</div>
</li>
</ul>
</li>
<li>
<div>
<a href="#starttls">starttls</a>
</div>
</li>
<li>
<div>
<a href="#unbind">unbind</a>
</div>
</li>
</ul>
</div>
<div id="content">
<h1 id="ldapjs-client-api">ldapjs Client API</h1>
<div class="intro">
<p>This document covers the ldapjs client API and assumes that you are familiar
with LDAP. If you're not, read the <a href="guide.html">guide</a> first.</p>
</div>
<h1 id="create-a-client">Create a client</h1>
<p>The code to create a new client looks like:</p>
<pre><code class="language-js"><span class="hljs-keyword">const</span> ldap = <span class="hljs-built_in">require</span>(<span class="hljs-string">'ldapjs'</span>);
<span class="hljs-keyword">const</span> client = ldap.<span class="hljs-title function_">createClient</span>({
<span class="hljs-attr">url</span>: [<span class="hljs-string">'ldap://127.0.0.1:1389'</span>, <span class="hljs-string">'ldap://127.0.0.2:1389'</span>]
});
client.<span class="hljs-title function_">on</span>(<span class="hljs-string">'connectError'</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> {
<span class="hljs-comment">// handle connection error</span>
})
</code></pre>
<p>You can use <code>ldap://</code> or <code>ldaps://</code>; the latter would connect over SSL (note
that this will not use the LDAP TLS extended operation, but literally an SSL
connection to port 636, as in LDAP v2). The full set of options to create a
client is:</p>
<table>
<thead>
<tr>
<th>Attribute</th>
<th>Description</th>
</tr>
</thead>
<tbody><tr>
<td>url</td>
<td>A string or array of valid LDAP URL(s) (proto/host/port)</td>
</tr>
<tr>
<td>socketPath</td>
<td>Socket path if using AF_UNIX sockets</td>
</tr>
<tr>
<td>log</td>
<td>A compatible logger instance (Default: no-op logger)</td>
</tr>
<tr>
<td>timeout</td>
<td>Milliseconds client should let operations live for before timing out (Default: Infinity)</td>
</tr>
<tr>
<td>connectTimeout</td>
<td>Milliseconds client should wait before timing out on TCP connections (Default: OS default)</td>
</tr>
<tr>
<td>tlsOptions</td>
<td>Additional options passed to TLS connection layer when connecting via <code>ldaps://</code> (See: The TLS docs for node.js)</td>
</tr>
<tr>
<td>idleTimeout</td>
<td>Milliseconds after last activity before client emits idle event</td>
</tr>
<tr>
<td>reconnect</td>
<td>Try to reconnect when the connection gets lost (Default is false)</td>
</tr>
</tbody></table>
<h3 id="url">url</h3>
<p>This parameter takes a single connection string or an array of connection strings
as an input. In case an array is provided, the client tries to connect to the
servers in given order. To achieve random server strategy (e.g. to distribute
the load among the servers), please shuffle the array before passing it as an
argument.</p>
<h3 id="note-on-logger">Note On Logger</h3>
<p>A passed in logger is expected to conform to the <a href="https://www.npmjs.com/package/bunyan">Bunyan</a>
API. Specifically, the logger is expected to have a <code>child()</code> method. If a logger
is supplied that does not have such a method, then a shim version is added
that merely returns the passed in logger.</p>
<p>Known compatible loggers are:</p>
<ul>
<li><a href="https://www.npmjs.com/package/bunyan">Bunyan</a></li>
<li><a href="https://www.npmjs.com/package/pino">Pino</a></li>
</ul>
<h3 id="note-on-error-handling">Note On Error Handling</h3>
<p>The client is an <code>EventEmitter</code>. If you don't register an error handler and
e.g. a connection error occurs, Node.js will print a stack trace and exit the
process (<a href="https://nodejs.org/api/events.html#error-events">reference</a>).</p>
<h2 id="connection-management">Connection management</h2>
<p>As LDAP is a stateful protocol (as opposed to HTTP), having connections torn
down from underneath you can be difficult to deal with. Several mechanisms
have been provided to mitigate this trouble.</p>
<h3 id="reconnect">Reconnect</h3>
<p>You can provide a Boolean option indicating if a reconnect should be tried. For
more sophisticated control, you can provide an Object with the properties
<code>initialDelay</code> (default: <code>100</code>), <code>maxDelay</code> (default: <code>10000</code>) and
<code>failAfter</code> (default: <code>Infinity</code>).
After the reconnect you maybe need to <a href="#bind">bind</a> again.</p>
<h2 id="client-events">Client events</h2>
<p>The client is an <code>EventEmitter</code> and can emit the following events:</p>
<table>
<thead>
<tr>
<th>Event</th>
<th>Description</th>
</tr>
</thead>
<tbody><tr>
<td>error</td>
<td>General error</td>
</tr>
<tr>
<td>connectRefused</td>
<td>Server refused connection. Most likely bad authentication</td>
</tr>
<tr>
<td>connectTimeout</td>
<td>Server timeout</td>
</tr>
<tr>
<td>connectError</td>
<td>Socket connection error</td>
</tr>
<tr>
<td>setupError</td>
<td>Setup error after successful connection</td>
</tr>
<tr>
<td>socketTimeout</td>
<td>Socket timeout</td>
</tr>
<tr>
<td>resultError</td>
<td>Search result error</td>
</tr>
<tr>
<td>timeout</td>
<td>Search result timeout</td>
</tr>
<tr>
<td>destroy</td>
<td>After client is disconnected</td>
</tr>
<tr>
<td>end</td>
<td>Socket end event</td>
</tr>
<tr>
<td>close</td>
<td>Socket closed</td>
</tr>
<tr>
<td>connect</td>
<td>Client connected</td>
</tr>
<tr>
<td>idle</td>
<td>Idle timeout reached</td>
</tr>
</tbody></table>
<h2 id="common-patterns">Common patterns</h2>
<p>The last two parameters in every API are <code>controls</code> and <code>callback</code>. <code>controls</code>
can be either a single instance of a <code>Control</code> or an array of <code>Control</code> objects.
You can, and probably will, omit this option.</p>
<p>Almost every operation has the callback form of <code>function(err, res)</code> where err
will be an instance of an <code>LDAPError</code> (you can use <code>instanceof</code> to switch).
You probably won't need to check the <code>res</code> parameter, but it's there if you do.</p>
<h1 id="bind">bind</h1>
<p><code>bind(dn, password, controls, callback)</code></p>
<p>Performs a bind operation against the LDAP server.</p>
<p>The bind API only allows LDAP 'simple' binds (equivalent to HTTP Basic
Authentication) for now. Note that all client APIs can optionally take an array
of <code>Control</code> objects. You probably don't need them though...</p>
<p>Example:</p>
<pre><code class="language-js">client.<span class="hljs-title function_">bind</span>(<span class="hljs-string">'cn=root'</span>, <span class="hljs-string">'secret'</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> {
assert.<span class="hljs-title function_">ifError</span>(err);
});
</code></pre>
<h1 id="add">add</h1>
<p><code>add(dn, entry, controls, callback)</code></p>
<p>Performs an add operation against the LDAP server.</p>
<p>Allows you to add an entry (which is just a plain JS object), and as always,
controls are optional.</p>
<p>Example:</p>
<pre><code class="language-js"><span class="hljs-keyword">const</span> entry = {
<span class="hljs-attr">cn</span>: <span class="hljs-string">'foo'</span>,
<span class="hljs-attr">sn</span>: <span class="hljs-string">'bar'</span>,
<span class="hljs-attr">email</span>: [<span class="hljs-string">'[email protected]'</span>, <span class="hljs-string">'[email protected]'</span>],
<span class="hljs-attr">objectclass</span>: <span class="hljs-string">'fooPerson'</span>
};
client.<span class="hljs-title function_">add</span>(<span class="hljs-string">'cn=foo, o=example'</span>, entry, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> {
assert.<span class="hljs-title function_">ifError</span>(err);
});
</code></pre>
<h1 id="compare">compare</h1>
<p><code>compare(dn, attribute, value, controls, callback)</code></p>
<p>Performs an LDAP compare operation with the given attribute and value against
the entry referenced by dn.</p>
<p>Example:</p>
<pre><code class="language-js">client.<span class="hljs-title function_">compare</span>(<span class="hljs-string">'cn=foo, o=example'</span>, <span class="hljs-string">'sn'</span>, <span class="hljs-string">'bar'</span>, <span class="hljs-function">(<span class="hljs-params">err, matched</span>) =></span> {
assert.<span class="hljs-title function_">ifError</span>(err);
<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'matched: '</span> + matched);
});
</code></pre>
<h1 id="del">del</h1>
<p><code>del(dn, controls, callback)</code></p>
<p>Deletes an entry from the LDAP server.</p>
<p>Example:</p>
<pre><code class="language-js">client.<span class="hljs-title function_">del</span>(<span class="hljs-string">'cn=foo, o=example'</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> {
assert.<span class="hljs-title function_">ifError</span>(err);
});
</code></pre>
<h1 id="exop">exop</h1>
<p><code>exop(name, value, controls, callback)</code></p>
<p>Performs an LDAP extended operation against an LDAP server. <code>name</code> is typically
going to be an OID (well, the RFC says it must be; however, ldapjs has no such
restriction). <code>value</code> is completely arbitrary, and is whatever the exop says it
should be.</p>
<p>Example (performs an LDAP 'whois' extended op):</p>
<pre><code class="language-js">client.<span class="hljs-title function_">exop</span>(<span class="hljs-string">'1.3.6.1.4.1.4203.1.11.3'</span>, <span class="hljs-function">(<span class="hljs-params">err, value, res</span>) =></span> {
assert.<span class="hljs-title function_">ifError</span>(err);
<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'whois: '</span> + value);
});
</code></pre>
<h1 id="modify">modify</h1>
<p><code>modify(name, changes, controls, callback)</code></p>
<p>Performs an LDAP modify operation against the LDAP server. This API requires
you to pass in a <code>Change</code> object, which is described below. Note that you can
pass in a single <code>Change</code> or an array of <code>Change</code> objects.</p>
<p>Example:</p>
<pre><code class="language-js"><span class="hljs-keyword">const</span> change = <span class="hljs-keyword">new</span> ldap.<span class="hljs-title class_">Change</span>({
<span class="hljs-attr">operation</span>: <span class="hljs-string">'add'</span>,
<span class="hljs-attr">modification</span>: {
<span class="hljs-attr">type</span>: <span class="hljs-string">'pets'</span>,
<span class="hljs-attr">values</span>: [<span class="hljs-string">'cat'</span>, <span class="hljs-string">'dog'</span>]
}
});
client.<span class="hljs-title function_">modify</span>(<span class="hljs-string">'cn=foo, o=example'</span>, change, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> {
assert.<span class="hljs-title function_">ifError</span>(err);
});
</code></pre>
<h2 id="change">Change</h2>
<p>A <code>Change</code> object maps to the LDAP protocol of a modify change, and requires you
to set the <code>operation</code> and <code>modification</code>. The <code>operation</code> is a string, and
must be one of:</p>
<table>
<thead>
<tr>
<th>Operation</th>
<th>Description</th>
</tr>
</thead>
<tbody><tr>
<td>replace</td>
<td>Replaces the attribute referenced in <code>modification</code>. If the modification has no values, it is equivalent to a delete.</td>
</tr>
<tr>
<td>add</td>
<td>Adds the attribute value(s) referenced in <code>modification</code>. The attribute may or may not already exist.</td>
</tr>
<tr>
<td>delete</td>
<td>Deletes the attribute (and all values) referenced in <code>modification</code>.</td>
</tr>
</tbody></table>
<p><code>modification</code> is just a plain old JS object with the required type and values you want.</p>
<table>
<thead>
<tr>
<th>Operation</th>
<th>Description</th>
</tr>
</thead>
<tbody><tr>
<td>type</td>
<td>String that defines the attribute type for the modification.</td>
</tr>
<tr>
<td>values</td>
<td>Defines the values for modification.</td>
</tr>
</tbody></table>
<h1 id="modifydn">modifyDN</h1>
<p><code>modifyDN(dn, newDN, controls, callback)</code></p>
<p>Performs an LDAP modifyDN (rename) operation against an entry in the LDAP
server. A couple points with this client API:</p>
<ul>
<li>There is no ability to set "keep old dn." It's always going to flag the old
dn to be purged.</li>
<li>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).</li>
</ul>
<p>Example:</p>
<pre><code class="language-js">client.<span class="hljs-title function_">modifyDN</span>(<span class="hljs-string">'cn=foo, o=example'</span>, <span class="hljs-string">'cn=bar'</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> {
assert.<span class="hljs-title function_">ifError</span>(err);
});
</code></pre>
<h1 id="search">search</h1>
<p><code>search(base, options, controls, callback)</code></p>
<p>Performs a search operation against the LDAP server.</p>
<p>The search operation is more complex than the other operations, so this one
takes an <code>options</code> object for all the parameters. However, ldapjs makes some
defaults for you so that if you pass nothing in, it's pretty much equivalent
to an HTTP GET operation (i.e., base search against the DN, filter set to
always match).</p>
<p>Like every other operation, <code>base</code> is a DN string.</p>
<p>Options can be a string representing a valid LDAP filter or an object
containing the following fields:</p>
<table>
<thead>
<tr>
<th>Attribute</th>
<th>Description</th>
</tr>
</thead>
<tbody><tr>
<td>scope</td>
<td>One of <code>base</code>, <code>one</code>, or <code>sub</code>. Defaults to <code>base</code>.</td>
</tr>
<tr>
<td>filter</td>
<td>A string version of an LDAP filter (see below), or a programatically constructed <code>Filter</code> object. Defaults to <code>(objectclass=*)</code>.</td>
</tr>
<tr>
<td>attributes</td>
<td>attributes to select and return (if these are set, the server will return <em>only</em> these attributes). Defaults to the empty set, which means all attributes. You can provide a string if you want a single attribute or an array of string for one or many.</td>
</tr>
<tr>
<td>attrsOnly</td>
<td>boolean on whether you want the server to only return the names of the attributes, and not their values. Borderline useless. Defaults to false.</td>
</tr>
<tr>
<td>sizeLimit</td>
<td>the maximum number of entries to return. Defaults to 0 (unlimited).</td>
</tr>
<tr>
<td>timeLimit</td>
<td>the maximum amount of time the server should take in responding, in seconds. Defaults to 10. Lots of servers will ignore this.</td>
</tr>
<tr>
<td>paged</td>
<td>enable and/or configure automatic result paging</td>
</tr>
</tbody></table>
<p>Responses inside callback of the <code>search</code> method are an <code>EventEmitter</code> where you will get a notification for
each <code>searchEntry</code> that comes back from the server. You will additionally be able to listen for a <code>searchRequest</code>
, <code>searchReference</code>, <code>error</code> and <code>end</code> event.
<code>searchRequest</code> is emitted immediately after every <code>SearchRequest</code> is sent with a <code>SearchRequest</code> parameter. You can do operations
like <code>client.abandon</code> with <code>searchRequest.messageId</code> to abandon this search request. Note that the <code>error</code> event will
only be for client/TCP errors, not LDAP error codes like the other APIs. You'll want to check the LDAP status code
(likely for <code>0</code>) on the <code>end</code> event to assert success. LDAP search results can give you a lot of status codes, such as
time or size exceeded, busy, inappropriate matching, etc., which is why this method doesn't try to wrap up the code
matching.</p>
<p>Example:</p>
<pre><code class="language-js"><span class="hljs-keyword">const</span> opts = {
<span class="hljs-attr">filter</span>: <span class="hljs-string">'(&(l=Seattle)(email=*@foo.com))'</span>,
<span class="hljs-attr">scope</span>: <span class="hljs-string">'sub'</span>,
<span class="hljs-attr">attributes</span>: [<span class="hljs-string">'dn'</span>, <span class="hljs-string">'sn'</span>, <span class="hljs-string">'cn'</span>]
};
client.<span class="hljs-title function_">search</span>(<span class="hljs-string">'o=example'</span>, opts, <span class="hljs-function">(<span class="hljs-params">err, res</span>) =></span> {
assert.<span class="hljs-title function_">ifError</span>(err);
res.<span class="hljs-title function_">on</span>(<span class="hljs-string">'searchRequest'</span>, <span class="hljs-function">(<span class="hljs-params">searchRequest</span>) =></span> {
<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'searchRequest: '</span>, searchRequest.<span class="hljs-property">messageId</span>);
});
res.<span class="hljs-title function_">on</span>(<span class="hljs-string">'searchEntry'</span>, <span class="hljs-function">(<span class="hljs-params">entry</span>) =></span> {
<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'entry: '</span> + <span class="hljs-title class_">JSON</span>.<span class="hljs-title function_">stringify</span>(entry.<span class="hljs-property">pojo</span>));
});
res.<span class="hljs-title function_">on</span>(<span class="hljs-string">'searchReference'</span>, <span class="hljs-function">(<span class="hljs-params">referral</span>) =></span> {
<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'referral: '</span> + referral.<span class="hljs-property">uris</span>.<span class="hljs-title function_">join</span>());
});
res.<span class="hljs-title function_">on</span>(<span class="hljs-string">'error'</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> {
<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span class="hljs-string">'error: '</span> + err.<span class="hljs-property">message</span>);
});
res.<span class="hljs-title function_">on</span>(<span class="hljs-string">'end'</span>, <span class="hljs-function">(<span class="hljs-params">result</span>) =></span> {
<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'status: '</span> + result.<span class="hljs-property">status</span>);
});
});
</code></pre>
<h2 id="filter-strings">Filter Strings</h2>
<p>The easiest way to write search filters is to write them compliant with RFC2254,
which is "The string representation of LDAP search filters." Note that
ldapjs doesn't support extensible matching, since it's one of those features
that almost nobody actually uses in practice.</p>
<p>Assuming you don't really want to read the RFC, search filters in LDAP are
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 <code>email</code> with a value of <code>[email protected]</code>. The syntax would be:</p>
<pre><code>([email protected])
</code></pre>
<p>ldapjs requires all filters to be surrounded by '()' blocks. Ok, that was easy.
Let's now assume that you want to find all records where the email is actually
just anything in the "@bar.com" domain and the location attribute is set to
Seattle:</p>
<pre><code>(&(email=*@bar.com)(l=Seattle))
</code></pre>
<p>Now our filter is actually three LDAP filters. We have an <code>and</code> filter (single
amp <code>&</code>), an <code>equality</code> filter <code>(the l=Seattle)</code>, and a <code>substring</code> filter.
Substrings are wildcard filters. They use <code>*</code> as the wildcard. You can put more
than one wildcard for a given string. For example you could do <code>(email=*@*bar.com)</code>
to match any email of @bar.com or its subdomains like <code>"[email protected]"</code>.</p>
<p>Now, let's say we also want to set our filter to include a
specification that either the employeeType <em>not</em> be a manager nor a secretary:</p>
<pre><code>(&(email=*@bar.com)(l=Seattle)(!(|(employeeType=manager)(employeeType=secretary))))
</code></pre>
<p>The <code>not</code> character is represented as a <code>!</code>, the <code>or</code> as a single pipe <code>|</code>.
It gets a little bit complicated, but it's actually quite powerful, and lets you
find almost anything you're looking for.</p>
<h2 id="paging">Paging</h2>
<p>Many LDAP server enforce size limits upon the returned result set (commonly
1000). In order to retrieve results beyond this limit, a <code>PagedResultControl</code>
is passed between the client and server to iterate through the entire dataset.
While callers could choose to do this manually via the <code>controls</code> parameter to
<code>search()</code>, ldapjs has internal mechanisms to easily automate the process. The
most simple way to use the paging automation is to set the <code>paged</code> option to
true when performing a search:</p>
<pre><code class="language-js"><span class="hljs-keyword">const</span> opts = {
<span class="hljs-attr">filter</span>: <span class="hljs-string">'(objectclass=commonobject)'</span>,
<span class="hljs-attr">scope</span>: <span class="hljs-string">'sub'</span>,
<span class="hljs-attr">paged</span>: <span class="hljs-literal">true</span>,
<span class="hljs-attr">sizeLimit</span>: <span class="hljs-number">200</span>
};
client.<span class="hljs-title function_">search</span>(<span class="hljs-string">'o=largedir'</span>, opts, <span class="hljs-function">(<span class="hljs-params">err, res</span>) =></span> {
assert.<span class="hljs-title function_">ifError</span>(err);
res.<span class="hljs-title function_">on</span>(<span class="hljs-string">'searchEntry'</span>, <span class="hljs-function">(<span class="hljs-params">entry</span>) =></span> {
<span class="hljs-comment">// do per-entry processing</span>
});
res.<span class="hljs-title function_">on</span>(<span class="hljs-string">'page'</span>, <span class="hljs-function">(<span class="hljs-params">result</span>) =></span> {
<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'page end'</span>);
});
res.<span class="hljs-title function_">on</span>(<span class="hljs-string">'error'</span>, <span class="hljs-function">(<span class="hljs-params">resErr</span>) =></span> {
assert.<span class="hljs-title function_">ifError</span>(resErr);
});
res.<span class="hljs-title function_">on</span>(<span class="hljs-string">'end'</span>, <span class="hljs-function">(<span class="hljs-params">result</span>) =></span> {
<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'done '</span>);
});
});
</code></pre>
<p>This will enable paging with a default page size of 199 (<code>sizeLimit</code> - 1) and
will output all of the resulting objects via the <code>searchEntry</code> event. At the
end of each result during the operation, a <code>page</code> event will be emitted as
well (which includes the intermediate <code>searchResult</code> object).</p>
<p>For those wanting more precise control over the process, an object with several
parameters can be provided for the <code>paged</code> option. The <code>pageSize</code> parameter
sets the size of result pages requested from the server. If no value is
specified, it will fall back to the default (100 or <code>sizeLimit</code> - 1, to obey
the RFC). The <code>pagePause</code> parameter allows back-pressure to be exerted on the
paged search operation by pausing at the end of each page. When enabled, a
callback function is passed as an additional parameter to <code>page</code> events. The
client will wait to request the next page until that callback is executed.</p>
<p>Here is an example where both of those parameters are used:</p>
<pre><code class="language-js"><span class="hljs-keyword">const</span> queue = <span class="hljs-keyword">new</span> <span class="hljs-title class_">MyWorkQueue</span>(someSlowWorkFunction);
<span class="hljs-keyword">const</span> opts = {
<span class="hljs-attr">filter</span>: <span class="hljs-string">'(objectclass=commonobject)'</span>,
<span class="hljs-attr">scope</span>: <span class="hljs-string">'sub'</span>,
<span class="hljs-attr">paged</span>: {
<span class="hljs-attr">pageSize</span>: <span class="hljs-number">250</span>,
<span class="hljs-attr">pagePause</span>: <span class="hljs-literal">true</span>
},
};
client.<span class="hljs-title function_">search</span>(<span class="hljs-string">'o=largerdir'</span>, opts, <span class="hljs-function">(<span class="hljs-params">err, res</span>) =></span> {
assert.<span class="hljs-title function_">ifError</span>(err);
res.<span class="hljs-title function_">on</span>(<span class="hljs-string">'searchEntry'</span>, <span class="hljs-function">(<span class="hljs-params">entry</span>) =></span> {
<span class="hljs-comment">// Submit incoming objects to queue</span>
queue.<span class="hljs-title function_">push</span>(entry);
});
res.<span class="hljs-title function_">on</span>(<span class="hljs-string">'page'</span>, <span class="hljs-function">(<span class="hljs-params">result, cb</span>) =></span> {
<span class="hljs-comment">// Allow the queue to flush before fetching next page</span>
queue.<span class="hljs-title function_">cbWhenFlushed</span>(cb);
});
res.<span class="hljs-title function_">on</span>(<span class="hljs-string">'error'</span>, <span class="hljs-function">(<span class="hljs-params">resErr</span>) =></span> {
assert.<span class="hljs-title function_">ifError</span>(resErr);
});
res.<span class="hljs-title function_">on</span>(<span class="hljs-string">'end'</span>, <span class="hljs-function">(<span class="hljs-params">result</span>) =></span> {
<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'done'</span>);
});
});
</code></pre>
<h1 id="starttls">starttls</h1>
<p><code>starttls(options, controls, callback)</code></p>
<p>Attempt to secure existing LDAP connection via STARTTLS.</p>
<p>Example:</p>
<pre><code class="language-js"><span class="hljs-keyword">const</span> opts = {
<span class="hljs-attr">ca</span>: [fs.<span class="hljs-title function_">readFileSync</span>(<span class="hljs-string">'mycacert.pem'</span>)]
};
client.<span class="hljs-title function_">starttls</span>(opts, <span class="hljs-function">(<span class="hljs-params">err, res</span>) =></span> {
assert.<span class="hljs-title function_">ifError</span>(err);
<span class="hljs-comment">// Client communication now TLS protected</span>
});
</code></pre>
<h1 id="unbind">unbind</h1>
<p><code>unbind(callback)</code></p>
<p>Performs an unbind operation against the LDAP server.</p>
<p>Note that unbind operation is not an opposite operation
for bind. Unbinding results in disconnecting the client
regardless of whether a bind operation was performed.</p>
<p>The <code>callback</code> argument is optional as unbind does
not have a response.</p>
<p>Example:</p>
<pre><code class="language-js">client.<span class="hljs-title function_">unbind</span>(<span class="hljs-function">(<span class="hljs-params">err</span>) =></span> {
assert.<span class="hljs-title function_">ifError</span>(err);
});
</code></pre>
</div><!-- end #content -->
</body>
</html>