forked from ldapjs/ldapjs.github.io
-
Notifications
You must be signed in to change notification settings - Fork 0
/
filters.html
321 lines (303 loc) · 19.1 KB
/
filters.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
<!DOCTYPE html>
<html lang="en">
<head>
<title>Filters 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>Filters 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="#parsefilterfilterstring">parseFilter(filterString)</a>
</div>
</li>
<li>
<div>
<a href="#equalityfilter">EqualityFilter</a>
</div>
</li>
<li>
<div>
<a href="#presencefilter">PresenceFilter</a>
</div>
</li>
<li>
<div>
<a href="#substringfilter">SubstringFilter</a>
</div>
</li>
<li>
<div>
<a href="#greaterthanequalsfilter">GreaterThanEqualsFilter</a>
</div>
</li>
<li>
<div>
<a href="#lessthanequalsfilter">LessThanEqualsFilter</a>
</div>
</li>
<li>
<div>
<a href="#andfilter">AndFilter</a>
</div>
</li>
<li>
<div>
<a href="#orfilter">OrFilter</a>
</div>
</li>
<li>
<div>
<a href="#notfilter">NotFilter</a>
</div>
</li>
<li>
<div>
<a href="#approximatefilter">ApproximateFilter</a>
</div>
</li>
</ul>
</div>
<div id="content">
<h1 id="ldapjs-filters-api">ldapjs Filters API</h1>
<div class="intro">
<p>This document covers the ldapjs filters API and assumes that you are familiar
with LDAP. If you're not, read the <a href="guide.html">guide</a> first.</p>
</div>
<p>LDAP search filters are really the backbone of LDAP search operations, and
ldapjs tries to get you in "easy" with them if your dataset is small, and also
lets you introspect them if you want to write a "query planner". For reference,
make sure to read over <a href="http://www.ietf.org/rfc/rfc2254.txt">RFC2254</a>, as this
explains the LDAPv3 text filter representation.</p>
<p>ldapjs gives you a distinct object type mapping to each filter that is
context-sensitive. However, <em>all</em> filters have a <code>matches()</code> method on them, if
that's all you need. Most filters will have an <code>attribute</code> property on them,
since "simple" filters all operate on an attribute/value assertion. The
"complex" filters are really aggregations of other filters (i.e. 'and'), and so
these don't provide that property.</p>
<p>All Filters in the ldapjs framework extend from <code>Filter</code>, which wil have the
property <code>type</code> available; this will return a string name for the filter, and
will be one of:</p>
<h1 id="parsefilterfilterstring">parseFilter(filterString)</h1>
<p>Parses an <a href="http://www.ietf.org/rfc/rfc2254.txt">RFC2254</a> filter string into an
ldapjs object(s). If the filter is "complex", it will be a "tree" of objects.
For example:</p>
<pre><code class="language-js"><span class="hljs-keyword">const</span> parseFilter = <span class="hljs-built_in">require</span>(<span class="hljs-string">'ldapjs'</span>).<span class="hljs-property">parseFilter</span>;
<span class="hljs-keyword">const</span> f = <span class="hljs-title function_">parseFilter</span>(<span class="hljs-string">'(objectclass=*)'</span>);
</code></pre>
<p>Is a "simple" filter, and would just return a <code>PresenceFilter</code> object. However,</p>
<pre><code class="language-js"><span class="hljs-keyword">const</span> f = <span class="hljs-title function_">parseFilter</span>(<span class="hljs-string">'(&(employeeType=manager)(l=Seattle))'</span>);
</code></pre>
<p>Would return an <code>AndFilter</code>, which would have a <code>filters</code> array of two
<code>EqualityFilter</code> objects.</p>
<p><code>parseFilter</code> will throw if an invalid string is passed in (that is, a
syntactically invalid string).</p>
<h1 id="equalityfilter">EqualityFilter</h1>
<p>The equality filter is used to check exact matching of attribute/value
assertions. This object will have an <code>attribute</code> and <code>value</code> property, and the
<code>name</code> property will be <code>equal</code>.</p>
<p>The string syntax for an equality filter is <code>(attr=value)</code>.</p>
<p>The <code>matches()</code> method will return true IFF the passed in object has a
key matching <code>attribute</code> and a value matching <code>value</code>.</p>
<pre><code class="language-js"><span class="hljs-keyword">const</span> f = <span class="hljs-keyword">new</span> <span class="hljs-title class_">EqualityFilter</span>({
<span class="hljs-attr">attribute</span>: <span class="hljs-string">'cn'</span>,
<span class="hljs-attr">value</span>: <span class="hljs-string">'foo'</span>
});
f.<span class="hljs-title function_">matches</span>({<span class="hljs-attr">cn</span>: <span class="hljs-string">'foo'</span>}); => <span class="hljs-literal">true</span>
f.<span class="hljs-title function_">matches</span>({<span class="hljs-attr">cn</span>: <span class="hljs-string">'bar'</span>}); => <span class="hljs-literal">false</span>
</code></pre>
<p>Equality matching uses "strict" type JavaScript comparison, and by default
everything in ldapjs (and LDAP) is a UTF-8 string. If you want comparison
of numbers, or something else, you'll need to use a middleware interceptor
that transforms values of objects.</p>
<h1 id="presencefilter">PresenceFilter</h1>
<p>The presence filter is used to check if an object has an attribute at all, with
any value. This object will have an <code>attribute</code> property, and the <code>name</code>
property will be <code>present</code>.</p>
<p>The string syntax for a presence filter is <code>(attr=*)</code>.</p>
<p>The <code>matches()</code> method will return true IFF the passed in object has a
key matching <code>attribute</code>.</p>
<pre><code class="language-js"><span class="hljs-keyword">const</span> f = <span class="hljs-keyword">new</span> <span class="hljs-title class_">PresenceFilter</span>({
<span class="hljs-attr">attribute</span>: <span class="hljs-string">'cn'</span>
});
f.<span class="hljs-title function_">matches</span>({<span class="hljs-attr">cn</span>: <span class="hljs-string">'foo'</span>}); => <span class="hljs-literal">true</span>
f.<span class="hljs-title function_">matches</span>({<span class="hljs-attr">sn</span>: <span class="hljs-string">'foo'</span>}); => <span class="hljs-literal">false</span>
</code></pre>
<h1 id="substringfilter">SubstringFilter</h1>
<p>The substring filter is used to do wildcard matching of a string value. This
object will have an <code>attribute</code> property and then it will have an <code>initial</code>
property, which is the prefix match, an <code>any</code> which will be an array of strings
that are to be found <em>somewhere</em> in the target string, and a <code>final</code> property,
which will be the suffix match of the string. <code>any</code> and <code>final</code> are both
optional. The <code>name</code> property will be <code>substring</code>.</p>
<p>The string syntax for a presence filter is <code>(attr=foo*bar*cat*dog)</code>, which would
map to:</p>
<pre><code class="language-js">{
<span class="hljs-attr">initial</span>: <span class="hljs-string">'foo'</span>,
<span class="hljs-attr">any</span>: [<span class="hljs-string">'bar'</span>, <span class="hljs-string">'cat'</span>],
<span class="hljs-attr">final</span>: <span class="hljs-string">'dog'</span>
}
</code></pre>
<p>The <code>matches()</code> method will return true IFF the passed in object has a
key matching <code>attribute</code> and the "regex" matches the value</p>
<pre><code class="language-js"><span class="hljs-keyword">const</span> f = <span class="hljs-keyword">new</span> <span class="hljs-title class_">SubstringFilter</span>({
<span class="hljs-attr">attribute</span>: <span class="hljs-string">'cn'</span>,
<span class="hljs-attr">initial</span>: <span class="hljs-string">'foo'</span>,
<span class="hljs-attr">any</span>: [<span class="hljs-string">'bar'</span>],
<span class="hljs-attr">final</span>: <span class="hljs-string">'baz'</span>
});
f.<span class="hljs-title function_">matches</span>({<span class="hljs-attr">cn</span>: <span class="hljs-string">'foobigbardogbaz'</span>}); => <span class="hljs-literal">true</span>
f.<span class="hljs-title function_">matches</span>({<span class="hljs-attr">sn</span>: <span class="hljs-string">'fobigbardogbaz'</span>}); => <span class="hljs-literal">false</span>
</code></pre>
<h1 id="greaterthanequalsfilter">GreaterThanEqualsFilter</h1>
<p>The ge filter is used to do comparisons and ordering based on the value type. As
mentioned elsewhere, by default everything in LDAP and ldapjs is a string, so
this filter's <code>matches()</code> would be using lexicographical ordering of strings.
If you wanted <code>>=</code> semantics over numeric values, you would need to add some
middleware to convert values before comparison (and the value of the filter).
Note that the ldapjs schema middleware will do this.</p>
<p>The GreaterThanEqualsFilter will have an <code>attribute</code> property, a <code>value</code>
property and the <code>name</code> property will be <code>ge</code>.</p>
<p>The string syntax for a ge filter is:</p>
<pre><code>(cn>=foo)
</code></pre>
<p>The <code>matches()</code> method will return true IFF the passed in object has a
key matching <code>attribute</code> and the value is <code>>=</code> this filter's <code>value</code>.</p>
<pre><code class="language-js"><span class="hljs-keyword">const</span> f = <span class="hljs-keyword">new</span> <span class="hljs-title class_">GreaterThanEqualsFilter</span>({
<span class="hljs-attr">attribute</span>: <span class="hljs-string">'cn'</span>,
<span class="hljs-attr">value</span>: <span class="hljs-string">'foo'</span>,
});
f.<span class="hljs-title function_">matches</span>({<span class="hljs-attr">cn</span>: <span class="hljs-string">'foobar'</span>}); => <span class="hljs-literal">true</span>
f.<span class="hljs-title function_">matches</span>({<span class="hljs-attr">cn</span>: <span class="hljs-string">'abc'</span>}); => <span class="hljs-literal">false</span>
</code></pre>
<h1 id="lessthanequalsfilter">LessThanEqualsFilter</h1>
<p>The le filter is used to do comparisons and ordering based on the value type. As
mentioned elsewhere, by default everything in LDAP and ldapjs is a string, so
this filter's <code>matches()</code> would be using lexicographical ordering of strings.
If you wanted <code><=</code> semantics over numeric values, you would need to add some
middleware to convert values before comparison (and the value of the filter).
Note that the ldapjs schema middleware will do this.</p>
<p>The string syntax for a le filter is:</p>
<pre><code>(cn<=foo)
</code></pre>
<p>The LessThanEqualsFilter will have an <code>attribute</code> property, a <code>value</code>
property and the <code>name</code> property will be <code>le</code>.</p>
<p>The <code>matches()</code> method will return true IFF the passed in object has a
key matching <code>attribute</code> and the value is <code><=</code> this filter's <code>value</code>.</p>
<pre><code class="language-js"><span class="hljs-keyword">const</span> f = <span class="hljs-keyword">new</span> <span class="hljs-title class_">LessThanEqualsFilter</span>({
<span class="hljs-attr">attribute</span>: <span class="hljs-string">'cn'</span>,
<span class="hljs-attr">value</span>: <span class="hljs-string">'foo'</span>,
});
f.<span class="hljs-title function_">matches</span>({<span class="hljs-attr">cn</span>: <span class="hljs-string">'abc'</span>}); => <span class="hljs-literal">true</span>
f.<span class="hljs-title function_">matches</span>({<span class="hljs-attr">cn</span>: <span class="hljs-string">'foobar'</span>}); => <span class="hljs-literal">false</span>
</code></pre>
<h1 id="andfilter">AndFilter</h1>
<p>The and filter is a complex filter that simply contains "child" filters. The
object will have a <code>filters</code> property which is an array of <code>Filter</code> objects. The
<code>name</code> property will be <code>and</code>.</p>
<p>The string syntax for an and filter is (assuming below we're and'ing two
equality filters):</p>
<pre><code>(&(cn=foo)(sn=bar))
</code></pre>
<p>The <code>matches()</code> method will return true IFF the passed in object matches all
the filters in the <code>filters</code> array.</p>
<pre><code class="language-js"><span class="hljs-keyword">const</span> f = <span class="hljs-keyword">new</span> <span class="hljs-title class_">AndFilter</span>({
<span class="hljs-attr">filters</span>: [
<span class="hljs-keyword">new</span> <span class="hljs-title class_">EqualityFilter</span>({
<span class="hljs-attr">attribute</span>: <span class="hljs-string">'cn'</span>,
<span class="hljs-attr">value</span>: <span class="hljs-string">'foo'</span>
}),
<span class="hljs-keyword">new</span> <span class="hljs-title class_">EqualityFilter</span>({
<span class="hljs-attr">attribute</span>: <span class="hljs-string">'sn'</span>,
<span class="hljs-attr">value</span>: <span class="hljs-string">'bar'</span>
})
]
});
f.<span class="hljs-title function_">matches</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-literal">true</span>
f.<span class="hljs-title function_">matches</span>({<span class="hljs-attr">cn</span>: <span class="hljs-string">'foo'</span>, <span class="hljs-attr">sn</span>: <span class="hljs-string">'baz'</span>}); => <span class="hljs-literal">false</span>
</code></pre>
<h1 id="orfilter">OrFilter</h1>
<p>The or filter is a complex filter that simply contains "child" filters. The
object will have a <code>filters</code> property which is an array of <code>Filter</code> objects. The
<code>name</code> property will be <code>or</code>.</p>
<p>The string syntax for an or filter is (assuming below we're or'ing two
equality filters):</p>
<pre><code>(|(cn=foo)(sn=bar))
</code></pre>
<p>The <code>matches()</code> method will return true IFF the passed in object matches <em>any</em>
of the filters in the <code>filters</code> array.</p>
<pre><code class="language-js"><span class="hljs-keyword">const</span> f = <span class="hljs-keyword">new</span> <span class="hljs-title class_">OrFilter</span>({
<span class="hljs-attr">filters</span>: [
<span class="hljs-keyword">new</span> <span class="hljs-title class_">EqualityFilter</span>({
<span class="hljs-attr">attribute</span>: <span class="hljs-string">'cn'</span>,
<span class="hljs-attr">value</span>: <span class="hljs-string">'foo'</span>
}),
<span class="hljs-keyword">new</span> <span class="hljs-title class_">EqualityFilter</span>({
<span class="hljs-attr">attribute</span>: <span class="hljs-string">'sn'</span>,
<span class="hljs-attr">value</span>: <span class="hljs-string">'bar'</span>
})
]
});
f.<span class="hljs-title function_">matches</span>({<span class="hljs-attr">cn</span>: <span class="hljs-string">'foo'</span>, <span class="hljs-attr">sn</span>: <span class="hljs-string">'baz'</span>}); => <span class="hljs-literal">true</span>
f.<span class="hljs-title function_">matches</span>({<span class="hljs-attr">cn</span>: <span class="hljs-string">'bar'</span>, <span class="hljs-attr">sn</span>: <span class="hljs-string">'baz'</span>}); => <span class="hljs-literal">false</span>
</code></pre>
<h1 id="notfilter">NotFilter</h1>
<p>The not filter is a complex filter that contains a single "child" filter. The
object will have a <code>filter</code> property which is an instance of a <code>Filter</code> object.
The <code>name</code> property will be <code>not</code>.</p>
<p>The string syntax for a not filter is (assuming below we're not'ing an
equality filter):</p>
<pre><code>(!(cn=foo))
</code></pre>
<p>The <code>matches()</code> method will return true IFF the passed in object does not match
the filter in the <code>filter</code> property.</p>
<pre><code class="language-js"><span class="hljs-keyword">const</span> f = <span class="hljs-keyword">new</span> <span class="hljs-title class_">NotFilter</span>({
<span class="hljs-attr">filter</span>: <span class="hljs-keyword">new</span> <span class="hljs-title class_">EqualityFilter</span>({
<span class="hljs-attr">attribute</span>: <span class="hljs-string">'cn'</span>,
<span class="hljs-attr">value</span>: <span class="hljs-string">'foo'</span>
})
});
f.<span class="hljs-title function_">matches</span>({<span class="hljs-attr">cn</span>: <span class="hljs-string">'bar'</span>}); => <span class="hljs-literal">true</span>
f.<span class="hljs-title function_">matches</span>({<span class="hljs-attr">cn</span>: <span class="hljs-string">'foo'</span>}); => <span class="hljs-literal">false</span>
</code></pre>
<h1 id="approximatefilter">ApproximateFilter</h1>
<p>The approximate filter is used to check "approximate" matching of
attribute/value assertions. This object will have an <code>attribute</code> and
<code>value</code> property, and the <code>name</code> property will be <code>approx</code>.</p>
<p>As a side point, this is a useless filter. It's really only here if you have
some whacky client that's sending this. It just does an exact match (which
is what ActiveDirectory does too).</p>
<p>The string syntax for an equality filter is <code>(attr~=value)</code>.</p>
<p>The <code>matches()</code> method will return true IFF the passed in object has a
key matching <code>attribute</code> and a value exactly matching <code>value</code>.</p>
<pre><code class="language-js"><span class="hljs-keyword">const</span> f = <span class="hljs-keyword">new</span> <span class="hljs-title class_">ApproximateFilter</span>({
<span class="hljs-attr">attribute</span>: <span class="hljs-string">'cn'</span>,
<span class="hljs-attr">value</span>: <span class="hljs-string">'foo'</span>
});
f.<span class="hljs-title function_">matches</span>({<span class="hljs-attr">cn</span>: <span class="hljs-string">'foo'</span>}); => <span class="hljs-literal">true</span>
f.<span class="hljs-title function_">matches</span>({<span class="hljs-attr">cn</span>: <span class="hljs-string">'bar'</span>}); => <span class="hljs-literal">false</span>
</code></pre>
</div><!-- end #content -->
</body>
</html>