server .js.html
server.js , create ldap database server - clients socket
ldapjs Server API
This document covers the ldapjs server API and assumes that you are familiar with LDAP. If you're not, read the guide first.
Create a server
The code to create a new server looks like:
<code class="language-js"><span class="hljs-keyword">const</span> server = ldap.<span class="hljs-title function_">createServer</span>();
The full list of options is:
||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 certificate for SSL.||
Note On Logger
The passed in logger is expected to conform to the Log4j standard API. Internally, abstract-logging is used to implement the interface. As a result, no log messages will be generated unless an external logger is supplied.
Known compatible loggers are:
Properties on the server object
maxConnections
Set this property to reject connections when the server's connection count gets high.
connections (getter only) - DEPRECATED
The number of concurrent connections on the server. This property is deprecated, please use server.getConnections() instead.
url
Returns the fully qualified URL this server is listening on. For example: ldaps://192.16.0.1:636
. If you haven't yet called listen
, it will always return ldap://localhost:389
.
Event: 'close'
function() {}
Emitted when the server closes.
Listening for requests
The LDAP server API wraps up and mirrors the node.js server.listen
family of APIs.
After calling listen
, the property url
on the server object itself will be available.
Example:
<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-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>);
});
Port and Host
listen(port, [host], [callback])
Begin accepting connections on the specified port and host. If the host is omitted, the server will accept connections directed to any IPv4 address (INADDR_ANY).
This function is asynchronous. The last parameter callback will be called when the server has been bound.
Unix Domain Socket
listen(path, [callback])
Start a UNIX socket server listening for connections on the given path.
This function is asynchronous. The last parameter callback will be called when the server has been bound.
File descriptor
listenFD(fd)
Start a server listening for connections on the given file descriptor.
This file descriptor must have already had the bind(2)
and listen(2)
system calls invoked on it. Additionally, it must be set non-blocking; try fcntl(fd, F_SETFL, O_NONBLOCK)
.
Inspecting server state
server.getConnections(callback)
The LDAP server API mirrors the Node.js server.getConnections
API. Callback should take two arguments err and count.
Routes
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 OP(req, res, next)
where OP is one of bind, add, del, etc. You can chain handlers together by calling next()
and ordering your functions in the definition of the route. For example:
<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">'dc=example,dc=e'</span>, authorize, <span class="hljs-keyword">function</span>(<span class="hljs-params">req, res, next</span>) { ... });
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.
For example ldapjs-riak is a complete implementation of the LDAP protocol over Riak. Getting an LDAP server up with riak looks like:
<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">"dc=example,dc=e"</span>, backend, backend.<span class="hljs-title function_">add</span>()); ...
The first parameter to an ldapjs route is always the point in the tree to mount the handler chain at. The second argument is optionally a backend object. After that you can pass in an arbitrary combination of functions in the form f(req, res, next)
or arrays of functions of the same signature (ldapjs will unroll them).
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 .use()
method availabe, similar to that on express/connect, allowing you to chain up "middleware":
<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>();
});
Common Request Elements
All request objects have the dn
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 dn
. The DN object itself is documented at DN.
All requests have an optional array of Control
objects. Control
will have the properties type
(string), criticality
(boolean), and optionally, a string value
.
All request objects will have a connection
object, which is the net.Socket
associated to this request. Off the connection
object is an ldap
object. The most important property to pay attention to is the bindDN
property which will be an instance of an ldap.DN
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 cn=anonymous
.
Additionally, request will have a logId
parameter you can use to uniquely identify the request/connection pair in logs (includes the LDAP messageID).
Common Response Elements
All response objects will have an end
method on them. By default, calling res.end()
with no arguments will return SUCCESS (0x00) to the client (with the exception of compare
which will return COMPARE_TRUE (0x06)). You can pass in a status code to the end()
method to return an alternate status code.
However, it's more common/easier to use the return next(new LDAPError())
pattern, since ldapjs will fill in the extra LDAPResult fields like matchedDN and error message for you.
Errors
ldapjs includes an exception hierarchy that directly corresponds to the RFC list of error codes. The complete list is documented in errors. But the paradigm is something defined like CONSTRAINT_VIOLATION in the RFC would be ConstraintViolationError
in ldapjs. Upon calling next(new LDAPError())
, ldapjs will stop calling your handler chain. For example:
<code class="language-js">server.<span class="hljs-title function_">search</span>(<span class="hljs-string">'dc=example,dc=e'</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>(); }
);
In the code snipped above, the third handler would never get invoked.
Bind
Adds a mount in the tree to perform LDAP binds with. Example:
<code class="language-js">server.<span class="hljs-title function_">bind</span>(<span class="hljs-string">'ou=people, dc=example,dc=e'</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>();
});
BindRequest
BindRequest objects have the following properties:
version
The LDAP protocol version the client is requesting to run this connection on. Note that ldapjs only supports LDAP version 3.
name
The DN the client is attempting to bind as (note this is the same as the dn
property).
authentication
The method of authentication. Right now only simple
is supported.
credentials
The credentials to go with the name/authentication
pair. For simple
, this will be the plain-text password.
BindResponse
No extra methods above an LDAPResult
API call.
Add
Adds a mount in the tree to perform LDAP adds with.
<code class="language-js">server.<span class="hljs-title function_">add</span>(<span class="hljs-string">'ou=people, dc=example,dc=e'</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>();
});
AddRequest
AddRequest objects have the following properties:
entry
The DN the client is attempting to add (this is the same as the dn
property).
attributes
The set of attributes in this entry. This will be an array of Attribute
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 toObject()
and iterate that way, since that will transform an AddRequest into a standard JavaScript object.
toObject()
This operation will return a plain JavaScript object from the request that looks like:
<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>]
}
}
AddResponse
No extra methods above an LDAPResult
API call.
Search
Adds a handler for the LDAP search operation.
<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>();
});
SearchRequest
SearchRequest objects have the following properties:
baseObject
The DN the client is attempting to start the search at (equivalent to dn
).
scope
(string) one of:
- base
- one
- sub
derefAliases
An integer (defined in the LDAP protocol). Defaults to '0' (meaning never deref).
sizeLimit
The number of entries to return. Defaults to '0' (unlimited). ldapjs doesn't currently automatically enforce this, but probably will at some point.
timeLimit
Maximum amount of time the server should take in sending search entries. Defaults to '0' (unlimited).
typesOnly
Whether to return only the names of attributes, and not the values. Defaults to 'false'. ldapjs will take care of this for you.
filter
The filter object that the client requested. Notably this has a matches()
method on it that you can leverage. For an example of introspecting a filter, take a look at the ldapjs-riak source.
attributes
An optional list of attributes to restrict the returned result sets to. ldapjs will automatically handle this for you.
SearchResponse
send(entry)
Allows you to send a SearchEntry
object. You do not need to explicitly pass in a SearchEntry
object, and can instead just send a plain JavaScript object that matches the format used from AddRequest.toObject()
.
<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>();
});
modify
Allows you to handle an LDAP modify operation.
<code class="language-js">server.<span class="hljs-title function_">modify</span>(<span class="hljs-string">'dc=example,e'</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>();
});
ModifyRequest
ModifyRequest objects have the following properties:
object
The DN the client is attempting to update (this is the same as the dn
property).
changes
An array of Change
objects the client is attempting to perform. See below for details on the Change
object.
Change
The Change
object will have the following properties:
operation
A string, and will be one of: 'add', 'delete', or 'replace'.
modification
Will be an Attribute
object, which will have a 'type' (string) field, and 'vals', which will be an array of string values.
ModifyResponse
No extra methods above an LDAPResult
API call.
del
Allows you to handle an LDAP delete operation.
<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>();
});
DeleteRequest
entry
The DN the client is attempting to delete (this is the same as the dn
property).
DeleteResponse
No extra methods above an LDAPResult
API call.
compare
Allows you to handle an LDAP compare operation.
<code class="language-js">server.<span class="hljs-title function_">compare</span>(<span class="hljs-string">'dc=example,e=e'</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>);
});
CompareRequest
entry
The DN the client is attempting to compare (this is the same as the dn
property).
attribute
The string name of the attribute to compare values of.
value
The string value of the attribute to compare.
CompareResponse
The end()
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 LDAPResult
API call.
modifyDN
Allows you to handle an LDAP modifyDN operation.
<code class="language-js">server.<span class="hljs-title function_">modifyDN</span>(<span class="hljs-string">'dc=example,dc=e'</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>();
});
ModifyDNRequest
entry
The DN the client is attempting to rename (this is the same as the dn
property).
newRdn
The leaf RDN the client wants to rename this entry to. This will be a DN object.
deleteOldRdn
Whether or not to delete the old RDN (i.e., rename vs copy). Defaults to 'true'.
newSuperior
Optional (DN). If the modifyDN operation wishes to relocate the entry in the tree, the newSuperior
field will contain the new parent.
ModifyDNResponse
No extra methods above an LDAPResult
API call.
exop
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.
<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>();
});
ExtendedRequest
name
Will always be a match to the route-defined name. Clients must include this in their requests.
value
Optional string. The arbitrary blob the client sends for this extended operation.
ExtendedResponse
name
The name of the extended operation. ldapjs will automatically set this.
value
The arbitrary (string) value to send back as part of the response.
unbind
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.
<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>();
});
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 net.Socket.end()
for you. There are no properties available on either the request or response objects, except, of course, for end()
on the response.
