ldap_ex v0.2.6 LDAPEx.Client View Source
This handles the LDAP communications over the TCP or SSL connections.
Link to this section Summary
Functions
Returns a specification to start this module under a supervisor.
This will close the supplied LDAPEx.Client
.
This returns an object by a full object name, optionally can specify specific
attributes to return, otherwise it returns all. This function ignores
references and will only return a single full object result. If more than one
object matched then the dn was not precise enough and it will return an
{:error, reason}
2-tuple.
Invoked when the server is started. start_link/3
or start/3
will
block until it returns.
This performs a search in the LDAP connection using the record created by
LDAPEx.Client.setup_search/1
.
This sets up a search record, this should then be passed into
LDAPEx.Client.search/3
to perform the search. The :baseObject
and
:filter
options are the minimum necessary to be supplied.
Call this to start the client and link it to your process so it will be cleaned when your process exits, it will return {:ok, pid}. Any of the default config options can (and should be if not specified in the config) be specified here as a keyword list.
Link to this section Functions
Returns a specification to start this module under a supervisor.
See Supervisor
.
This will close the supplied LDAPEx.Client
.
iex> {:ok, ldap} = LDAPEx.Client.start_link()
iex> is_pid(ldap)
true
iex> LDAPEx.Client.close(ldap)
:ok
get_object(ldap, dn, attributes \\ [], genserver_timeout \\ 120000)
View SourceThis returns an object by a full object name, optionally can specify specific
attributes to return, otherwise it returns all. This function ignores
references and will only return a single full object result. If more than one
object matched then the dn was not precise enough and it will return an
{:error, reason}
2-tuple.
iex> {:ok, ldap} = LDAPEx.Client.start_link()
iex> {:ok, obj} = LDAPEx.Client.get_object(ldap, System.get_env("TEST_LDAP_DN"))
iex> obj.objectName === System.get_env("TEST_LDAP_DN")
true
iex> map_size(obj.attributes) >= 1
true
iex> LDAPEx.Client.close(ldap)
:ok
Invoked when the server is started. start_link/3
or start/3
will
block until it returns.
init_arg
is the argument term (second argument) passed to start_link/3
.
Returning {:ok, state}
will cause start_link/3
to return
{:ok, pid}
and the process to enter its loop.
Returning {:ok, state, timeout}
is similar to {:ok, state}
,
except that it also sets a timeout. See the "Timeouts" section
in the module documentation for more information.
Returning {:ok, state, :hibernate}
is similar to {:ok, state}
except the process is hibernated before entering the loop. See
c:handle_call/3
for more information on hibernation.
Returning {:ok, state, {:continue, continue}}
is similar to
{:ok, state}
except that immediately after entering the loop
the c:handle_continue/2
callback will be invoked with the value
continue
as first argument.
Returning :ignore
will cause start_link/3
to return :ignore
and
the process will exit normally without entering the loop or calling
c:terminate/2
. If used when part of a supervision tree the parent
supervisor will not fail to start nor immediately try to restart the
GenServer
. The remainder of the supervision tree will be started
and so the GenServer
should not be required by other processes.
It can be started later with Supervisor.restart_child/2
as the child
specification is saved in the parent supervisor. The main use cases for
this are:
- The
GenServer
is disabled by configuration but might be enabled later. - An error occurred and it will be handled by a different mechanism than the
Supervisor
. Likely this approach involves callingSupervisor.restart_child/2
after a delay to attempt a restart.
Returning {:stop, reason}
will cause start_link/3
to return
{:error, reason}
and the process to exit with reason reason
without
entering the loop or calling c:terminate/2
.
Callback implementation for GenServer.init/1
.
search(ldap, searchRecord, genserver_timeout \\ 120000, controls \\ :asn1_NOVALUE)
View SourceThis performs a search in the LDAP connection using the record created by
LDAPEx.Client.setup_search/1
.
iex> {:ok, ldap} = LDAPEx.Client.start_link()
iex> req = LDAPEx.Client.setup_search(baseObject: System.get_env("TEST_LDAP_DN"), filter: {:present, "objectClass"} )
iex> {:ok, {res, _references}} = LDAPEx.Client.search(ldap, req) # _refs are just an empty [] in every server tested so far...
iex> [r] = res # Assuming only one record is returned
iex> r.objectName === System.get_env("TEST_LDAP_DN")
true
iex> map_size(r.attributes) >= 1
true
iex> LDAPEx.Client.close(ldap)
:ok
This sets up a search record, this should then be passed into
LDAPEx.Client.search/3
to perform the search. The :baseObject
and
:filter
options are the minimum necessary to be supplied.
Details on the LDAP Searching spec can be found at the LDAP Website - The Search Operation
Details about LDAP Filters can be found at the LDAP Website - Filters.
All possible options are:
:baseObject
-> Specifies the base DN for the search. Only entries at or below this location in the server (based on the scope) will be considered potential matches.:scope
-> Specifies the range of entries relative to the base DN that may be considered potential matches. By default it is:wholeSubtree
, which can be slow for many operations. Can also be set to the atoms:singleLevel
or:baseObject
.:derefAliases
-> Specifies the behavior that the server should exhibit if any alias entries are encountered while processing the search. This should generally always be left at its default atom of:derefAlways
, however its other options are the atoms of:derefFindingBaseObj
,:derefInSearching
, and:neverDerefAliases
.:sizeLimit
-> An integer that specifies the maximum number of entries that should be returned from the search. A value of zero indicates that there should not be any limit enforced. Note that the directory server may also be configured with a server-side size limit which can also limit the number of entries that may be returned to the client and in that case the smaller of the client-side and server-side limits will be used. If no size limit is provided, then a default of zero (unlimited) will be used.:timeLimit
-> Specifies the maximum length of time in seconds that the server should spend processing the search. A value of zero indicates that there should not be any limit enforced. Note that the directory server may also be configured with a server-side time limit which can also limit the processing time, and in that case the smaller of the client-side and server-side limits will be used. If no time limit is provided, then a default of the initial connection timeout value will be used.:typesOnly
-> Indicates whether matching entries should include only attribute names, or both attribute names and values. If no value is provided, then a default offalse
will be used. Other option istrue
. If it istrue
then the attribute values will just be the empty list[]
.:filter
-> A filter is a 2-tuple of one of the following:{:and, [<AnotherFilter>]}
-> And takes a list of other filters and requires them all.{:or, [<AnotherFilter>]}
-> Or takes a list of other filters and requires them all.{:not, <AnotherFilter}
-> Not will invert another Filter.{:equalityMatch, {:AttributeValueAssertion, "<AttributeKey>", "<AttributeValue>"}}
-> Equality Match takes an attribute key string and an attribute value string then filters on if the value matches the attribute value on the object.{:substrings, {:SubstringFilter, "<AttributeKey>", [<SubstringMatcher>]}}
-> Substring takes an Attribute Key string, and a list of SubstringMaterchers, which are a 2-tuple of{:initial|:any|:final, "<String>"}
.{:greaterOrEqual, {:AttributeValueAssertion, "<AttributeKey>", "<AttributeValue"}}
-> GreaterOrEqual takes an attribute key string and an attribute value string then filters on if the value is greater or equal to the attribute value on the object.{:lessOrEqual, {:AttributeValueAssertion, "<AttributeKey>", "<AttributeValue>"}}
-> LessOrEqual takes an attribute key string and an attribute value string then filters on if the value is less or equal to the attribute value on the object.- {:present, "
"} -> Present takes a single string and will match to an object if it contains that Attribute Key at all, or filters it out if it does not have that Attribute key. {:approxMatch, {:AttributeValueAssertion, "<AttributeKey>", "<AttributeValue>"}}
-> ApproxMatch takes an attribute key string and an attribute value string then filters on if the value is approximately to the attribute value on the object. By 'approximately' this means that the implementation is entirely defined by and dependent on the server. It might be phonetic, so something like 'John' could match 'Jon', or it could be a LIKE type thing so "Joh*" could match "John" or "Johnny" or whatever it is the server wants to do.{:extensibleMatch, {:MatchingRuleAssertion, matchingRule = :asn1_NOVALUE, type = :asn1_NOVALUE, matchValue, dnAttributes = :asn1_DEFAULT}}
-> The Extensible Match is the most complex, but also the most powerful matcher that LDAP has to offer. Please see the "Extensible Match Filters" section on the above LDAP Filters link for details. 'matchingRule', 'type', and 'matchValue' are all strings, and 'dnAttributes' is a boolean. 'matchValue' is the only required field, the rest may be left at the defaults that are listed above to have the server ignore those fields. The atom:asn1_DEFAULT
ondnAttributes
is equal tofalse
.
:attributes
-> A list of strings, default [], will return only the specified attributes, if empty it returns all.
iex> LDAPEx.Client.setup_search(baseObject: "ou=People,o=example.com,o=cp", filter: {:present, "dn"} )
{:SearchRequest, "ou=People,o=example.com,o=cp", :wholeSubtree,
:derefAlways, 0, :undefined, false, {:present, "dn"}, []}
Call this to start the client and link it to your process so it will be cleaned when your process exits, it will return {:ok, pid}. Any of the default config options can (and should be if not specified in the config) be specified here as a keyword list.
iex> {:ok, ldap} = LDAPEx.Client.start_link()
iex> is_pid(ldap)
true
# Anon login
iex> {:ok, ldap} = LDAPEx.Client.start_link(username: "", password: "")
iex> is_pid(ldap)
true
iex> LDAPEx.Client.start_link(username: "INVALID", password: "")
{:error, :invalidDNSyntax}
iex> LDAPEx.Client.start_link(username: System.get_env("TEST_LDAP_DN"), password: "INCORRECT")
{:error, :invalidCredentials}