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
Link to this function

get_object(ldap, dn, attributes \\ [], genserver_timeout \\ 120000)

View Source

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.


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 calling Supervisor.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.

Link to this function

search(ldap, searchRecord, genserver_timeout \\ 120000, controls \\ :asn1_NOVALUE)

View Source

This 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
Link to this function

setup_search(searchRequestArgs \\ [])

View Source

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 of false will be used. Other option is true. If it is true 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 on dnAttributes is equal to false.
  • :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"}, []}
Link to this function

start_link(overrides \\ [])

View Source

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}