1eldap(3) Erlang Module Definition eldap(3)
2
6 eldap - LDAP Client
7
9 This module provides a client api to the Lightweight Directory Access
10 Protocol (LDAP).
11 References:
13 * RFC 4510 - RFC 4519
15 * RFC 2830
17 The above publications can be found at IETF.
19
21 Type definitions that are used more than once in this module:
22 handle():
24 Connection handle
25 attribute() =:
27 {Type = string(), Values=[string()]}
28 modify_op():
30 See mod_add/2, mod_delete/2, mod_replace/2
31 scope():
33 See baseObject/0, singleLevel/0, wholeSubtree/0
34 dereference():
36 See neverDerefAliases/0, derefInSearching/0, derefFindingBaseObj/0,
37 derefAlways/0
38 filter():
40 See present/1, substrings/2, equalityMatch/2, greaterOrEqual/2,
41 lessOrEqual/2, approxMatch/2, extensibleMatch/2, 'and'/1, 'or'/1,
42 'not'/1
43 return_value() = :
45 ok | {ok, {referral,referrals()}} | {error,Error}
46 referrals() =:
48 [Address = string()] The contents of Address is server dependent.
49
51 open([Host]) -> {ok, Handle} | {error, Reason}
52 Types:
54 Handle = handle()
56 Setup a connection to an LDAP server, the HOST's are tried in
58 order.
59 open([Host], [Option]) -> {ok, Handle} | {error, Reason}
61 Types:
63 Handle = handle()
65 Option = {port, integer()} | {log, function()} | {timeout,
66 integer()} | {ssl, boolean()} | {sslopts, list()} | {tcpopts,
67 list()}
68 Setup a connection to an LDAP server, the HOST's are tried in
70 order.
71 The log function takes three arguments, fun(Level, FormatString,
73 [FormatArg]) end.
74 Timeout set the maximum time in milliseconds that each server
76 request may take.
77 All TCP socket options are accepted except active, binary, de‐
79 liver, list, mode and packet
80 close(Handle) -> ok
82 Types:
84 Handle = handle()
86 Shutdown the connection after sending an unbindRequest to the
88 server. If the connection is tls the connection will be closed
89 with ssl:close/1, otherwise with gen_tcp:close/1.
90 start_tls(Handle, Options) -> return_value()
92 Same as start_tls(Handle, Options, infinity)
94 start_tls(Handle, Options, Timeout) -> return_value()
96 Types:
98 Handle = handle()
100 Options = ssl:ssl_options()
101 Timeout = infinity | positive_integer()
102 Upgrade the connection associated with Handle to a tls connec‐
104 tion if possible.
105 The upgrade is done in two phases: first the server is asked for
107 permission to upgrade. Second, if the request is acknowledged,
108 the upgrade to tls is performed.
109 Error responses from phase one will not affect the current en‐
111 cryption state of the connection. Those responses are:
112 tls_already_started:
114 The connection is already encrypted. The connection is not
115 affected.
116 {response,ResponseFromServer}:
118 The upgrade was refused by the LDAP server. The Response‐
119 FromServer is an atom delivered byt the LDAP server ex‐
120 plained in section 2.3 of rfc 2830. The connection is not
121 affected, so it is still un-encrypted.
122 Errors in the second phase will however end the connection:
124 Error:
126 Any error responded from ssl:connect/3
127 The Timeout parameter is for the actual tls upgrade (phase 2)
129 while the timeout in eldap:open/2 is used for the initial nego‐
130 tiation about upgrade (phase 1).
131 simple_bind(Handle, Dn, Password) -> return_value()
133 Types:
135 Handle = handle()
137 Dn = string()
138 Password = string()
139 Authenticate the connection using simple authentication.
141 add(Handle, Dn, [Attribute]) -> return_value()
143 Types:
145 Handle = handle()
147 Dn = string()
148 Attribute = attribute()
149 Add an entry. The entry must not exist.
151 add(Handle,
153 "cn=Bill Valentine, ou=people, o=Example Org, dc=example, dc=com",
154 [{"objectclass", ["person"]},
155 {"cn", ["Bill Valentine"]},
156 {"sn", ["Valentine"]},
157 {"telephoneNumber", ["545 555 00"]}]
158 )
159 delete(Handle, Dn) -> return_value()
162 Types:
164 Dn = string()
166 Delete an entry.
168 delete(Handle, "cn=Bill Valentine, ou=people, o=Example Org, dc=example, dc=com")
170 mod_add(Type, [Value]) -> modify_op()
173 Types:
175 Type = string()
177 Value = string()
178 Create an add modification operation.
180 mod_delete(Type, [Value]) -> modify_op()
182 Types:
184 Type = string()
186 Value = string()
187 Create a delete modification operation.
189 mod_replace(Type, [Value]) -> modify_op()
191 Types:
193 Type = string()
195 Value = string()
196 Create a replace modification operation.
198 modify(Handle, Dn, [ModifyOp]) -> return_value()
200 Types:
202 Dn = string()
204 ModifyOp = modify_op()
205 Modify an entry.
207 modify(Handle, "cn=Bill Valentine, ou=people, o=Example Org, dc=example, dc=com",
209 [eldap:mod_replace("telephoneNumber", ["555 555 00"]),
210 eldap:mod_add("description", ["LDAP Hacker"]) ])
211 modify_password(Handle, Dn, NewPasswd) -> return_value() | {ok, Gen‐
214 Passwd}
215 Types:
217 Dn = string()
219 NewPasswd = string()
220 Modify the password of a user. See modify_password/4.
222 modify_password(Handle, Dn, NewPasswd, OldPasswd) -> return_value() |
224 {ok, GenPasswd}
225 Types:
227 Dn = string()
229 NewPasswd = string()
230 OldPasswd = string()
231 GenPasswd = string()
232 Modify the password of a user.
234 * Dn. The user to modify. Should be "" if the modify request
236 is for the user of the LDAP session.
237 * NewPasswd. The new password to set. Should be "" if the
239 server is to generate the password. In this case, the result
240 will be {ok, GenPasswd}.
241 * OldPasswd. Sometimes required by server policy for a user to
243 change their password. If not required, use modify_pass‐
244 word/3.
245 modify_dn(Handle, Dn, NewRDN, DeleteOldRDN, NewSupDN) -> return_value()
247 Types:
249 Dn = string()
251 NewRDN = string()
252 DeleteOldRDN = boolean()
253 NewSupDN = string()
254 Modify the DN of an entry. DeleteOldRDN indicates whether the
256 current RDN should be removed from the attribute list after the
257 operation. NewSupDN is the new parent that the RDN shall be
258 moved to. If the old parent should remain as parent, NewSupDN
259 shall be "".
260 modify_dn(Handle, "cn=Bill Valentine, ou=people, o=Example Org, dc=example, dc=com ",
262 "cn=Bill Jr Valentine", true, "")
263 search(Handle, SearchOptions) -> {ok, #eldap_search_result{}} | {ok,
266 {referral,referrals()}} | {error, Reason}
267 Types:
269 SearchOptions = #eldap_search{} | [SearchOption]
271 SearchOption = {base, string()} | {filter, filter()} |
272 {scope, scope()} | {attributes, [string()]} | {deref, deref‐
273 erence()} | | {types_only, boolean()} | {timeout, integer()}
274 Search the directory with the supplied the SearchOptions. The
276 base and filter options must be supplied. Default values: scope
277 is wholeSubtree(), deref is derefAlways(), types_only is false
278 and timeout is 0 (meaning infinity).
279 Filter = eldap:substrings("cn", [{any,"V"}]),
281 search(Handle, [{base, "dc=example, dc=com"}, {filter, Filter}, {attributes, ["cn"]}]),
282 The timeout option in the SearchOptions is for the ldap server,
285 while the timeout in eldap:open/2 is used for each individual
286 request in the search operation.
287 baseObject() -> scope()
289 Search baseobject only.
291 singleLevel() -> scope()
293 Search the specified level only, i.e. do not recurse.
295 wholeSubtree() -> scope()
297 Search the entire subtree.
299 neverDerefAliases() -> dereference()
301 Never dereference aliases, treat aliases as entries.
303 derefAlways() -> dereference()
305 Always dereference aliases.
307 derefInSearching() -> dereference()
309 Dereference aliases only when searching.
311 derefFindingBaseObj() -> dereference()
313 Dereference aliases only in finding the base.
315 present(Type) -> filter()
317 Types:
319 Type = string()
321 Create a filter which filters on attribute type presence.
323 substrings(Type, [SubString]) -> filter()
325 Types:
327 Type = string()
329 SubString = {StringPart, string()}
330 StringPart = initial | any | final
331 Create a filter which filters on substrings.
333 equalityMatch(Type, Value) -> filter()
335 Types:
337 Type = string()
339 Value = string()
340 Create a equality filter.
342 greaterOrEqual(Type, Value) -> filter()
344 Types:
346 Type = string()
348 Value = string()
349 Create a greater or equal filter.
351 lessOrEqual(Type, Value) -> filter()
353 Types:
355 Type = string()
357 Value = string()
358 Create a less or equal filter.
360 approxMatch(Type, Value) -> filter()
362 Types:
364 Type = string()
366 Value = string()
367 Create a approximation match filter.
369 extensibleMatch(MatchValue, OptionalAttrs) -> filter()
371 Types:
373 MatchValue = string()
375 OptionalAttrs = [Attr]
376 Attr = {matchingRule,string()} | {type,string()} | {dnAt‐
377 tributes,boolean()}
378 Creates an extensible match filter. For example,
380 eldap:extensibleMatch("Bar", [{type,"sn"}, {matchingRule,"caseExactMatch"}]))
382 creates a filter which performs a caseExactMatch on the attri‐
385 bute sn and matches with the value "Bar". The default value of
386 dnAttributes is false.
387 'and'([Filter]) -> filter()
389 Types:
391 Filter = filter()
393 Creates a filter where all Filter must be true.
395 'or'([Filter]) -> filter()
397 Types:
399 Filter = filter()
401 Create a filter where at least one of the Filter must be true.
403 'not'(Filter) -> filter()
405 Types:
407 Filter = filter()
409 Negate a filter.
411 paged_result_control(PageSize) -> {control, "1.2.840.113556.1.4.319",
413 true, binary()}
414 Types:
416 PageSize = positive_integer()
418 Paged results is an extension to the LDAP protocol specified by
420 RFC2696
421 This function creates a control with the specified page size for
423 use in search/3, for example:
424 Control = eldap:paged_result_control(50),
426 {ok, SearchResults} = search(Handle, [{base, "dc=example, dc=com"}], [Control]),
427 paged_result_control(PageSize, Cookie) -> {control,
430 "1.2.840.113556.1.4.319", true, binary()}
431 Types:
433 PageSize = positive_integer()
435 Cookie = binary()
436 Paged results is an extension to the LDAP protocol specified by
438 RFC2696
439 This function creates a control with the specified page size and
441 cookie for use in search/3 to retrieve the next results page.
442 For example:
444 PageSize = 50,
446 Control1 = eldap:paged_result_control(PageSize),
447 {ok, SearchResults1} = search(Handle, [{base, "dc=example, dc=com"}], [Control1]),
448 %% retrieve the returned cookie from the search results
449 {ok, Cookie1} = eldap:paged_result_cookie(SearchResults1),
450 Control2 = eldap:paged_result_control(PageSize, Cookie1),
451 {ok, SearchResults2} = eldap:search(Handle, [{base, "dc=example,dc=com"}], [Control2]),
452 %% etc
453 paged_result_cookie(SearchResult) -> binary()
456 Types:
458 SearchResult = #eldap_search_result{}
460 Paged results is an extension to the LDAP protocol specified by
462 RFC2696.
463 This function extracts the cookie returned from the server as a
465 result of a paged search result.
466 If the returned cookie is the empty string "", then these search
468 results represent the last in the series.
469 info(Handle) -> connection_info()
471 Types:
473 connection_info() = #{socket := Socket, socket_type := tcp |
475 ssl}
476 Socket = ssl:sslsocket() | gen_tcp:socket()
477 Currently available information reveals the socket and the
479 transport protocol, TCP or TLS (SSL), used by the LDAP connec‐
480 tion.
481Ericsson AB eldap 1.2.11 eldap(3)