This repository has been archived by the owner on May 14, 2024. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 2
/
server.html
646 lines (631 loc) · 33.4 KB
/
server.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
639
640
641
642
643
644
645
646
<!DOCTYPE html>
<html lang="en">
<head>
<title>Server 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>Server 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-server">Create a server</a>
</div>
<ul>
<li>
<div>
<a href="#properties-on-the-server-object">Properties on the server object</a>
</div>
</li>
<li>
<div>
<a href="#listening-for-requests">Listening for requests</a>
</div>
</li>
<li>
<div>
<a href="#inspecting-server-state">Inspecting server state</a>
</div>
</li>
</ul>
</li>
<li>
<div>
<a href="#routes">Routes</a>
</div>
<ul>
<li>
<div>
<a href="#common-request-elements">Common Request Elements</a>
</div>
</li>
<li>
<div>
<a href="#common-response-elements">Common Response Elements</a>
</div>
</li>
<li>
<div>
<a href="#errors">Errors</a>
</div>
</li>
</ul>
</li>
<li>
<div>
<a href="#bind">Bind</a>
</div>
<ul>
<li>
<div>
<a href="#bindrequest">BindRequest</a>
</div>
</li>
<li>
<div>
<a href="#bindresponse">BindResponse</a>
</div>
</li>
</ul>
</li>
<li>
<div>
<a href="#add">Add</a>
</div>
<ul>
<li>
<div>
<a href="#addrequest">AddRequest</a>
</div>
</li>
<li>
<div>
<a href="#addresponse">AddResponse</a>
</div>
</li>
</ul>
</li>
<li>
<div>
<a href="#search">Search</a>
</div>
<ul>
<li>
<div>
<a href="#searchrequest">SearchRequest</a>
</div>
</li>
<li>
<div>
<a href="#searchresponse">SearchResponse</a>
</div>
</li>
</ul>
</li>
<li>
<div>
<a href="#modify">modify</a>
</div>
<ul>
<li>
<div>
<a href="#modifyrequest">ModifyRequest</a>
</div>
</li>
<li>
<div>
<a href="#change">Change</a>
</div>
</li>
<li>
<div>
<a href="#modifyresponse">ModifyResponse</a>
</div>
</li>
</ul>
</li>
<li>
<div>
<a href="#del">del</a>
</div>
<ul>
<li>
<div>
<a href="#deleterequest">DeleteRequest</a>
</div>
</li>
<li>
<div>
<a href="#deleteresponse">DeleteResponse</a>
</div>
</li>
</ul>
</li>
<li>
<div>
<a href="#compare">compare</a>
</div>
<ul>
<li>
<div>
<a href="#comparerequest">CompareRequest</a>
</div>
</li>
<li>
<div>
<a href="#compareresponse">CompareResponse</a>
</div>
</li>
</ul>
</li>
<li>
<div>
<a href="#modifydn">modifyDN</a>
</div>
<ul>
<li>
<div>
<a href="#modifydnrequest">ModifyDNRequest</a>
</div>
</li>
<li>
<div>
<a href="#modifydnresponse">ModifyDNResponse</a>
</div>
</li>
</ul>
</li>
<li>
<div>
<a href="#exop">exop</a>
</div>
<ul>
<li>
<div>
<a href="#extendedrequest">ExtendedRequest</a>
</div>
</li>
<li>
<div>
<a href="#extendedresponse">ExtendedResponse</a>
</div>
</li>
</ul>
</li>
<li>
<div>
<a href="#unbind">unbind</a>
</div>
</li>
</ul>
</div>
<div id="content">
<h1 id="ldapjs-server-api">ldapjs Server API</h1>
<div class="intro">
<p>This document covers the ldapjs server 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-server">Create a server</h1>
<p>The code to create a new server looks like:</p>
<pre><code class="language-js"><span class="hljs-keyword">const</span> server = ldap.<span class="hljs-title function_">createServer</span>();
</code></pre>
<p>The full list of options is:</p>
<p>||log||You can optionally pass in a Bunyan compatible logger instance the client will use to acquire a child logger.||
||certificate||A PEM-encoded X.509 certificate; will cause this server to run in TLS mode.||
||key||A PEM-encoded private key that corresponds to <em>certificate</em> for SSL.||</p>
<h3 id="note-on-logger">Note On Logger</h3>
<p>The passed in logger is expected to conform to the Log4j standard API.
Internally, <a href="https://www.npmjs.com/packages/abstract-logging">abstract-logging</a> is
used to implement the interface. As a result, no log messages will be generated
unless an external logger is supplied.</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>
<h2 id="properties-on-the-server-object">Properties on the server object</h2>
<h3 id="maxconnections">maxConnections</h3>
<p>Set this property to reject connections when the server's connection count gets
high.</p>
<h3 id="connections-getter-only---deprecated">connections (getter only) - DEPRECATED</h3>
<p>The number of concurrent connections on the server. This property is deprecated,
please use server.getConnections() instead.</p>
<h3 id="url">url</h3>
<p>Returns the fully qualified URL this server is listening on. For example:
<code>ldaps://10.1.2.3:1636</code>. If you haven't yet called <code>listen</code>, it will always
return <code>ldap://localhost:389</code>.</p>
<h3 id="event-close">Event: 'close'</h3>
<p><code>function() {}</code></p>
<p>Emitted when the server closes.</p>
<h2 id="listening-for-requests">Listening for requests</h2>
<p>The LDAP server API wraps up and mirrors the node.js <code>server.listen</code> family of
APIs.</p>
<p>After calling <code>listen</code>, the property <code>url</code> on the server object itself will be
available.</p>
<p>Example:</p>
<pre><code class="language-js"> server.<span class="hljs-title function_">listen</span>(<span class="hljs-number">389</span>, <span class="hljs-string">'127.0.0.1'</span>, <span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) {
<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'LDAP server listening at: '</span> + server.<span class="hljs-property">url</span>);
});
</code></pre>
<h3 id="port-and-host">Port and Host</h3>
<p><code>listen(port, [host], [callback])</code></p>
<p>Begin accepting connections on the specified port and host. If the host is
omitted, the server will accept connections directed to the IPv4 address
<code>127.0.0.1</code>. To listen on any other address, supply said address as the <code>host</code>
parameter. For example, to listen on all available IPv6 addresses supply
<code>::</code> as the <code>host</code> (note, this <em>may</em> also result in listening on all
available IPv4 addresses, depending on operating system behavior).</p>
<p>We highly recommend being as explicit as possible with the <code>host</code> parameter.
Listening on all available addresses (through <code>::</code> or <code>0.0.0.0</code>) can lead
to potential security issues.</p>
<p>This function is asynchronous. The last parameter callback will be called when
the server has been bound.</p>
<h3 id="unix-domain-socket">Unix Domain Socket</h3>
<p><code>listen(path, [callback])</code></p>
<p>Start a UNIX socket server listening for connections on the given path.</p>
<p>This function is asynchronous. The last parameter callback will be called when
the server has been bound.</p>
<h3 id="file-descriptor">File descriptor</h3>
<p><code>listenFD(fd)</code></p>
<p>Start a server listening for connections on the given file descriptor.</p>
<p>This file descriptor must have already had the <code>bind(2)</code> and <code>listen(2)</code> system
calls invoked on it. Additionally, it must be set non-blocking; try
<code>fcntl(fd, F_SETFL, O_NONBLOCK)</code>.</p>
<h2 id="inspecting-server-state">Inspecting server state</h2>
<h3 id="servergetconnectionscallback">server.getConnections(callback)</h3>
<p>The LDAP server API mirrors the <a href="https://nodejs.org/dist/latest-v12.x/docs/api/net.html#net_server_getconnections_callback">Node.js <code>server.getConnections</code> API</a>. Callback
should take two arguments err and count.</p>
<h1 id="routes">Routes</h1>
<p>The LDAP server API is meant to be the LDAP-equivalent of the express/restify
paradigm of programming. Essentially every method is of the form
<code>OP(req, res, next)</code> where OP is one of bind, add, del, etc. You can chain
handlers together by calling <code>next()</code> and ordering your functions in the
definition of the route. For example:</p>
<pre><code class="language-js"><span class="hljs-keyword">function</span> <span class="hljs-title function_">authorize</span>(<span class="hljs-params">req, res, next</span>) {
<span class="hljs-keyword">if</span> (!req.<span class="hljs-property">connection</span>.<span class="hljs-property">ldap</span>.<span class="hljs-property">bindDN</span>.<span class="hljs-title function_">equals</span>(<span class="hljs-string">'cn=root'</span>))
<span class="hljs-keyword">return</span> <span class="hljs-title function_">next</span>(<span class="hljs-keyword">new</span> ldap.<span class="hljs-title class_">InsufficientAccessRightsError</span>());
<span class="hljs-keyword">return</span> <span class="hljs-title function_">next</span>();
}
server.<span class="hljs-title function_">search</span>(<span class="hljs-string">'o=example'</span>, authorize, <span class="hljs-keyword">function</span>(<span class="hljs-params">req, res, next</span>) { ... });
</code></pre>
<p>Note that ldapjs is also slightly different, since it's often going to be backed
to a DB-like entity, in that it also has an API where you can pass in a
'backend' object. This is necessary if there are persistent connection pools,
caching, etc. that need to be placed in an object.</p>
<p>For example <a href="https://github.com/mcavage/node-ldapjs-riak">ldapjs-riak</a> is a
complete implementation of the LDAP protocol over
<a href="https://github.com/basho/riak">Riak</a>. Getting an LDAP server up with riak
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> ldapRiak = <span class="hljs-built_in">require</span>(<span class="hljs-string">'ldapjs-riak'</span>);
<span class="hljs-keyword">const</span> server = ldap.<span class="hljs-title function_">createServer</span>();
<span class="hljs-keyword">const</span> backend = ldapRiak.<span class="hljs-title function_">createBackend</span>({
<span class="hljs-string">"host"</span>: <span class="hljs-string">"localhost"</span>,
<span class="hljs-string">"port"</span>: <span class="hljs-number">8098</span>,
<span class="hljs-string">"bucket"</span>: <span class="hljs-string">"example"</span>,
<span class="hljs-string">"indexes"</span>: [<span class="hljs-string">"l"</span>, <span class="hljs-string">"cn"</span>],
<span class="hljs-string">"uniqueIndexes"</span>: [<span class="hljs-string">"uid"</span>],
<span class="hljs-string">"numConnections"</span>: <span class="hljs-number">5</span>
});
server.<span class="hljs-title function_">add</span>(<span class="hljs-string">"o=example"</span>,
backend,
backend.<span class="hljs-title function_">add</span>());
...
</code></pre>
<p>The first parameter to an ldapjs route is always the point in the
tree to mount the handler chain at. The second argument is <em>optionally</em> a
backend object. After that you can pass in an arbitrary combination of
functions in the form <code>f(req, res, next)</code> or arrays of functions of the same
signature (ldapjs will unroll them).</p>
<p>Unlike HTTP, LDAP operations do not have a heterogeneous wire format, so each
operation requires specific methods/fields on the request/response
objects. However, there is a <code>.use()</code> method availabe, similar to
that on express/connect, allowing you to chain up "middleware":</p>
<pre><code class="language-js">server.<span class="hljs-title function_">use</span>(<span class="hljs-keyword">function</span>(<span class="hljs-params">req, res, next</span>) {
<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'hello world'</span>);
<span class="hljs-keyword">return</span> <span class="hljs-title function_">next</span>();
});
</code></pre>
<h2 id="common-request-elements">Common Request Elements</h2>
<p>All request objects have the <code>dn</code> getter on it, which is "context-sensitive"
and returns the point in the tree that the operation wants to operate on. The
LDAP protocol itself sadly doesn't define operations this way, and has a unique
name for just about every op. So, ldapjs calls it <code>dn</code>. The DN object itself
is documented at <a href="dn.html">DN</a>.</p>
<p>All requests have an optional array of <code>Control</code> objects. <code>Control</code> will have
the properties <code>type</code> (string), <code>criticality</code> (boolean), and optionally, a
string <code>value</code>.</p>
<p>All request objects will have a <code>connection</code> object, which is the <code>net.Socket</code>
associated to this request. Off the <code>connection</code> object is an <code>ldap</code> object.
The most important property to pay attention to is the <code>bindDN</code> property
which will be an instance of an <code>ldap.DN</code> object. This is what the client
authenticated as on this connection. If the client didn't bind, then a DN object
will be there defaulted to <code>cn=anonymous</code>.</p>
<p>Additionally, request will have a <code>logId</code> parameter you can use to uniquely
identify the request/connection pair in logs (includes the LDAP messageId).</p>
<h2 id="common-response-elements">Common Response Elements</h2>
<p>All response objects will have an <code>end</code> method on them. By default, calling
<code>res.end()</code> with no arguments will return SUCCESS (0x00) to the client
(with the exception of <code>compare</code> which will return COMPARE_TRUE (0x06)). You
can pass in a status code to the <code>end()</code> method to return an alternate status
code.</p>
<p>However, it's more common/easier to use the <code>return next(new LDAPError())</code>
pattern, since ldapjs will fill in the extra LDAPResult fields like matchedDN
and error message for you.</p>
<h2 id="errors">Errors</h2>
<p>ldapjs includes an exception hierarchy that directly corresponds to the RFC list
of error codes. The complete list is documented in <a href="errors.html">errors</a>. But
the paradigm is something defined like CONSTRAINT_VIOLATION in the RFC would be
<code>ConstraintViolationError</code> in ldapjs. Upon calling <code>next(new LDAPError())</code>,
ldapjs will <em>stop</em> calling your handler chain. For example:</p>
<pre><code class="language-js">server.<span class="hljs-title function_">search</span>(<span class="hljs-string">'o=example'</span>,
<span class="hljs-function">(<span class="hljs-params">req, res, next</span>) =></span> { <span class="hljs-keyword">return</span> <span class="hljs-title function_">next</span>(); },
<span class="hljs-function">(<span class="hljs-params">req, res, next</span>) =></span> { <span class="hljs-keyword">return</span> <span class="hljs-title function_">next</span>(<span class="hljs-keyword">new</span> ldap.<span class="hljs-title class_">OperationsError</span>()); },
<span class="hljs-function">(<span class="hljs-params">req, res, next</span>) =></span> { res.<span class="hljs-title function_">end</span>(); }
);
</code></pre>
<p>In the code snipped above, the third handler would never get invoked.</p>
<h1 id="bind">Bind</h1>
<p>Adds a mount in the tree to perform LDAP binds with. Example:</p>
<pre><code class="language-js">server.<span class="hljs-title function_">bind</span>(<span class="hljs-string">'ou=people, o=example'</span>, <span class="hljs-function">(<span class="hljs-params">req, res, next</span>) =></span> {
<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'bind DN: '</span> + req.<span class="hljs-property">dn</span>.<span class="hljs-title function_">toString</span>());
<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'bind PW: '</span> + req.<span class="hljs-property">credentials</span>);
res.<span class="hljs-title function_">end</span>();
});
</code></pre>
<h2 id="bindrequest">BindRequest</h2>
<p>BindRequest objects have the following properties:</p>
<h3 id="version">version</h3>
<p>The LDAP protocol version the client is requesting to run this connection on.
Note that ldapjs only supports LDAP version 3.</p>
<h3 id="name">name</h3>
<p>The DN the client is attempting to bind as (note this is the same as the <code>dn</code>
property).</p>
<h3 id="authentication">authentication</h3>
<p>The method of authentication. Right now only <code>simple</code> is supported.</p>
<h3 id="credentials">credentials</h3>
<p>The credentials to go with the <code>name/authentication</code> pair. For <code>simple</code>, this
will be the plain-text password.</p>
<h2 id="bindresponse">BindResponse</h2>
<p>No extra methods above an <code>LDAPResult</code> API call.</p>
<h1 id="add">Add</h1>
<p>Adds a mount in the tree to perform LDAP adds with.</p>
<pre><code class="language-js">server.<span class="hljs-title function_">add</span>(<span class="hljs-string">'ou=people, o=example'</span>, <span class="hljs-function">(<span class="hljs-params">req, res, next</span>) =></span> {
<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'DN: '</span> + req.<span class="hljs-property">dn</span>.<span class="hljs-title function_">toString</span>());
<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'Entry attributes: '</span> + req.<span class="hljs-title function_">toObject</span>().<span class="hljs-property">attributes</span>);
res.<span class="hljs-title function_">end</span>();
});
</code></pre>
<h2 id="addrequest">AddRequest</h2>
<p>AddRequest objects have the following properties:</p>
<h3 id="entry">entry</h3>
<p>The DN the client is attempting to add (this is the same as the <code>dn</code>
property).</p>
<h3 id="attributes">attributes</h3>
<p>The set of attributes in this entry. This will be an array of
<code>Attribute</code> objects (which have a type and an array of values). This directly
maps to how the request came in off the wire. It's likely you'll want to use
<code>toObject()</code> and iterate that way, since that will transform an AddRequest into
a standard JavaScript object.</p>
<h3 id="toobject">toObject()</h3>
<p>This operation will return a plain JavaScript object from the request that looks
like:</p>
<pre><code class="language-js">{
<span class="hljs-attr">dn</span>: <span class="hljs-string">'cn=foo, o=example'</span>, <span class="hljs-comment">// string, not DN object</span>
<span class="hljs-attr">attributes</span>: {
<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">objectclass</span>: [<span class="hljs-string">'person'</span>, <span class="hljs-string">'top'</span>]
}
}
</code></pre>
<h2 id="addresponse">AddResponse</h2>
<p>No extra methods above an <code>LDAPResult</code> API call.</p>
<h1 id="search">Search</h1>
<p>Adds a handler for the LDAP search operation.</p>
<pre><code class="language-js">server.<span class="hljs-title function_">search</span>(<span class="hljs-string">'o=example'</span>, <span class="hljs-function">(<span class="hljs-params">req, res, next</span>) =></span> {
<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'base object: '</span> + req.<span class="hljs-property">dn</span>.<span class="hljs-title function_">toString</span>());
<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'scope: '</span> + req.<span class="hljs-property">scope</span>);
<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'filter: '</span> + req.<span class="hljs-property">filter</span>.<span class="hljs-title function_">toString</span>());
res.<span class="hljs-title function_">end</span>();
});
</code></pre>
<h2 id="searchrequest">SearchRequest</h2>
<p>SearchRequest objects have the following properties:</p>
<h3 id="baseobject">baseObject</h3>
<p>The DN the client is attempting to start the search at (equivalent to <code>dn</code>).</p>
<h3 id="scope">scope</h3>
<p>(string) one of:</p>
<ul>
<li>base</li>
<li>one</li>
<li>sub</li>
</ul>
<h3 id="derefaliases">derefAliases</h3>
<p>An integer (defined in the LDAP protocol). Defaults to '0' (meaning
never deref).</p>
<h3 id="sizelimit">sizeLimit</h3>
<p>The number of entries to return. Defaults to '0' (unlimited). ldapjs doesn't
currently automatically enforce this, but probably will at some point.</p>
<h3 id="timelimit">timeLimit</h3>
<p>Maximum amount of time the server should take in sending search entries.
Defaults to '0' (unlimited).</p>
<h3 id="typesonly">typesOnly</h3>
<p>Whether to return only the names of attributes, and not the values. Defaults to
'false'. ldapjs will take care of this for you.</p>
<h3 id="filter">filter</h3>
<p>The <a href="filters.html">filter</a> object that the client requested. Notably this has
a <code>matches()</code> method on it that you can leverage. For an example of
introspecting a filter, take a look at the ldapjs-riak source.</p>
<h3 id="attributes-1">attributes</h3>
<p>An optional list of attributes to restrict the returned result sets to. ldapjs
will automatically handle this for you.</p>
<h2 id="searchresponse">SearchResponse</h2>
<h3 id="sendentry">send(entry)</h3>
<p>Allows you to send a <code>SearchEntry</code> object. You do not need to
explicitly pass in a <code>SearchEntry</code> object, and can instead just send a plain
JavaScript object that matches the format used from <code>AddRequest.toObject()</code>.</p>
<pre><code class="language-js">server.<span class="hljs-title function_">search</span>(<span class="hljs-string">'o=example'</span>, <span class="hljs-function">(<span class="hljs-params">req, res, next</span>) =></span> {
<span class="hljs-keyword">const</span> obj = {
<span class="hljs-attr">dn</span>: <span class="hljs-string">'o=example'</span>,
<span class="hljs-attr">attributes</span>: {
<span class="hljs-attr">objectclass</span>: [<span class="hljs-string">'top'</span>, <span class="hljs-string">'organization'</span>],
<span class="hljs-attr">o</span>: [<span class="hljs-string">'example'</span>]
}
};
<span class="hljs-keyword">if</span> (req.<span class="hljs-property">filter</span>.<span class="hljs-title function_">matches</span>(obj))
res.<span class="hljs-title function_">send</span>(obj)
res.<span class="hljs-title function_">end</span>();
});
</code></pre>
<h1 id="modify">modify</h1>
<p>Allows you to handle an LDAP modify operation.</p>
<pre><code class="language-js">server.<span class="hljs-title function_">modify</span>(<span class="hljs-string">'o=example'</span>, <span class="hljs-function">(<span class="hljs-params">req, res, next</span>) =></span> {
<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'DN: '</span> + req.<span class="hljs-property">dn</span>.<span class="hljs-title function_">toString</span>());
<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'changes:'</span>);
<span class="hljs-keyword">for</span> (<span class="hljs-keyword">const</span> c <span class="hljs-keyword">of</span> req.<span class="hljs-property">changes</span>) {
<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">' operation: '</span> + c.<span class="hljs-property">operation</span>);
<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">' modification: '</span> + c.<span class="hljs-property">modification</span>.<span class="hljs-title function_">toString</span>());
}
res.<span class="hljs-title function_">end</span>();
});
</code></pre>
<h2 id="modifyrequest">ModifyRequest</h2>
<p>ModifyRequest objects have the following properties:</p>
<h3 id="object">object</h3>
<p>The DN the client is attempting to update (this is the same as the <code>dn</code>
property).</p>
<h3 id="changes">changes</h3>
<p>An array of <code>Change</code> objects the client is attempting to perform. See below for
details on the <code>Change</code> object.</p>
<h2 id="change">Change</h2>
<p>The <code>Change</code> object will have the following properties:</p>
<h3 id="operation">operation</h3>
<p>A string, and will be one of: 'add', 'delete', or 'replace'.</p>
<h3 id="modification">modification</h3>
<p>Will be an <code>Attribute</code> object, which will have a 'type' (string) field, and
'vals', which will be an array of string values.</p>
<h2 id="modifyresponse">ModifyResponse</h2>
<p>No extra methods above an <code>LDAPResult</code> API call.</p>
<h1 id="del">del</h1>
<p>Allows you to handle an LDAP delete operation.</p>
<pre><code class="language-js">server.<span class="hljs-title function_">del</span>(<span class="hljs-string">'o=example'</span>, <span class="hljs-function">(<span class="hljs-params">req, res, next</span>) =></span> {
<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'DN: '</span> + req.<span class="hljs-property">dn</span>.<span class="hljs-title function_">toString</span>());
res.<span class="hljs-title function_">end</span>();
});
</code></pre>
<h2 id="deleterequest">DeleteRequest</h2>
<h3 id="entry-1">entry</h3>
<p>The DN the client is attempting to delete (this is the same as the <code>dn</code>
property).</p>
<h2 id="deleteresponse">DeleteResponse</h2>
<p>No extra methods above an <code>LDAPResult</code> API call.</p>
<h1 id="compare">compare</h1>
<p>Allows you to handle an LDAP compare operation.</p>
<pre><code class="language-js">server.<span class="hljs-title function_">compare</span>(<span class="hljs-string">'o=example'</span>, <span class="hljs-function">(<span class="hljs-params">req, res, next</span>) =></span> {
<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'DN: '</span> + req.<span class="hljs-property">dn</span>.<span class="hljs-title function_">toString</span>());
<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'attribute name: '</span> + req.<span class="hljs-property">attribute</span>);
<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'attribute value: '</span> + req.<span class="hljs-property">value</span>);
res.<span class="hljs-title function_">end</span>(req.<span class="hljs-property">value</span> === <span class="hljs-string">'foo'</span>);
});
</code></pre>
<h2 id="comparerequest">CompareRequest</h2>
<h3 id="entry-2">entry</h3>
<p>The DN the client is attempting to compare (this is the same as the <code>dn</code>
property).</p>
<h3 id="attribute">attribute</h3>
<p>The string name of the attribute to compare values of.</p>
<h3 id="value">value</h3>
<p>The string value of the attribute to compare.</p>
<h2 id="compareresponse">CompareResponse</h2>
<p>The <code>end()</code> method for compare takes a boolean, as opposed to a numeric code
(you can still pass in a numeric LDAP status code if you want). Beyond
that, there are no extra methods above an <code>LDAPResult</code> API call.</p>
<h1 id="modifydn">modifyDN</h1>
<p>Allows you to handle an LDAP modifyDN operation.</p>
<pre><code class="language-js">server.<span class="hljs-title function_">modifyDN</span>(<span class="hljs-string">'o=example'</span>, <span class="hljs-function">(<span class="hljs-params">req, res, next</span>) =></span> {
<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'DN: '</span> + req.<span class="hljs-property">dn</span>.<span class="hljs-title function_">toString</span>());
<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'new RDN: '</span> + req.<span class="hljs-property">newRdn</span>.<span class="hljs-title function_">toString</span>());
<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'deleteOldRDN: '</span> + req.<span class="hljs-property">deleteOldRdn</span>);
<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'new superior: '</span> +
(req.<span class="hljs-property">newSuperior</span> ? req.<span class="hljs-property">newSuperior</span>.<span class="hljs-title function_">toString</span>() : <span class="hljs-string">''</span>));
res.<span class="hljs-title function_">end</span>();
});
</code></pre>
<h2 id="modifydnrequest">ModifyDNRequest</h2>
<h3 id="entry-3">entry</h3>
<p>The DN the client is attempting to rename (this is the same as the <code>dn</code>
property).</p>
<h3 id="newrdn">newRdn</h3>
<p>The leaf RDN the client wants to rename this entry to. This will be a DN object.</p>
<h3 id="deleteoldrdn">deleteOldRdn</h3>
<p>Whether or not to delete the old RDN (i.e., rename vs copy). Defaults to 'true'.</p>
<h3 id="newsuperior">newSuperior</h3>
<p>Optional (DN). If the modifyDN operation wishes to relocate the entry in the
tree, the <code>newSuperior</code> field will contain the new parent.</p>
<h2 id="modifydnresponse">ModifyDNResponse</h2>
<p>No extra methods above an <code>LDAPResult</code> API call.</p>
<h1 id="exop">exop</h1>
<p>Allows you to handle an LDAP extended operation. Extended operations are pretty
much arbitrary extensions, by definition. Typically the extended 'name' is an
OID, but ldapjs makes no such restrictions; it just needs to be a string.
Unlike the other operations, extended operations don't map to any location in
the tree, so routing here will be exact match, as opposed to subtree.</p>
<pre><code class="language-js"><span class="hljs-comment">// LDAP whoami</span>
server.<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">req, res, next</span>) =></span> {
<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'name: '</span> + req.<span class="hljs-property">name</span>);
<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'value: '</span> + req.<span class="hljs-property">value</span>);
res.<span class="hljs-property">value</span> = <span class="hljs-string">'u:xxyyz@EXAMPLE.NET'</span>;
res.<span class="hljs-title function_">end</span>();
<span class="hljs-keyword">return</span> <span class="hljs-title function_">next</span>();
});
</code></pre>
<h2 id="extendedrequest">ExtendedRequest</h2>
<h3 id="name-1">name</h3>
<p>Will always be a match to the route-defined name. Clients must include this
in their requests.</p>
<h3 id="value-1">value</h3>
<p>Optional string. The arbitrary blob the client sends for this extended
operation.</p>
<h2 id="extendedresponse">ExtendedResponse</h2>
<h3 id="name-2">name</h3>
<p>The name of the extended operation. ldapjs will automatically set this.</p>
<h3 id="value-2">value</h3>
<p>The arbitrary (string) value to send back as part of the response.</p>
<h1 id="unbind">unbind</h1>
<p>ldapjs by default provides an unbind handler that just disconnects the client
and cleans up any internals (in ldapjs core). You can override this handler
if you need to clean up any items in your backend, or perform any other cleanup
tasks you need to.</p>
<pre><code class="language-js">server.<span class="hljs-title function_">unbind</span>(<span class="hljs-function">(<span class="hljs-params">req, res, next</span>) =></span> {
res.<span class="hljs-title function_">end</span>();
});
</code></pre>
<p>Note that the LDAP unbind operation actually doesn't send any response (by
definition in the RFC), so the UnbindResponse is really just a stub that
ultimately calls <code>net.Socket.end()</code> for you. There are no properties available
on either the request or response objects, except, of course, for <code>end()</code> on the
response.</p>
</div><!-- end #content -->
</body>
</html>