ldap LDAP library interface module

This module provides access to the LDAP (Lightweight Directory Access Protocol) C API implemented in OpenLDAP 2.3 or newer. It is similar to the C API, with the notable differences that lists are manipulated via Python list operations and errors appear as exceptions. For far more detailed information on the C interface, please see the (expired) draft-ietf-ldapext-ldap-c-api-04. This documentation is current for the Python LDAP module, version 2.4.10.0. Source and binaries are available from http://www.python-ldap.org/.

Functions

This module defines the following functions:

ldap.initialize(uri[, trace_level=0[, trace_file=sys.stdout[, trace_stack_limit=None]]]) → LDAPObject object

Initializes a new connection object for accessing the given LDAP server, and return an LDAP object (see LDAPObject classes) used to perform operations on that server. Parameter uri has to be a valid LDAP URL.

Note that the C wrapper function :py:func:_ldap.initialize() is called which calls the OpenLDAP funtion ldap_initialize(). Calling this function just initializes the LDAP connection struct in the C API - nothing else. The first call to an operation method (bind, search etc.) then really opens the connection. Before that nothing is sent on the wire.

The optional arguments are for generating debug log information: trace_level specifies the amount of information being logged, trace_file specifies a file-like object as target of the debug log and trace_stack_limit specifies the stack limit of tracebacks in debug log.

Possible values for trace_level are 0 for no logging, 1 for only logging the method calls with arguments, 2 for logging the method calls with arguments and the complete results and 9 for also logging the traceback of method calls.

See also

RFC 4516 - Lightweight Directory Access Protocol (LDAP): Uniform Resource Locator

ldap.open(host[, port=PORT]) → LDAPObject object

Opens a new connection with an LDAP server, and return an LDAP object (see LDAPObject classes) used to perform operations on that server. host is a string containing solely the host name. port is an integer specifying the port where the LDAP server is listening (default is 389).

Note: Using this function is deprecated.

ldap.get_option(option) → int|string

This function returns the value of the global option specified by option.

ldap.set_option(option, invalue) → None

This function sets the value of the global option specified by option to invalue.

Constants

The module defines various constants. Note that some constants depend on the build options and which underlying libs were used or even on the version of the libs. So before using those constants the application has to explicitly check whether they are available.

General

ldap.PORT

The assigned TCP port number (389) that LDAP servers listen on.

ldap.SASL_AVAIL

Integer where a non-zero value indicates that python-ldap was built with support for SASL (Cyrus-SASL).

ldap.TLS_AVAIL

Integer where a non-zero value indicates that python-ldap was built with support for SSL/TLS (OpenSSL or similar libs).

Options

See also

ldap.conf{5} and ldap_get_options{3}

For use with functions :py:func:set_option() and :py:func:get_option() and methods :py:method:LDAPObject.set_option() and :py:method:LDAPObject.get_option() the following option identifiers are defined as constants:

ldap.OPT_API_FEATURE_INFO
ldap.OPT_API_INFO
ldap.OPT_CLIENT_CONTROLS
ldap.OPT_DEBUG_LEVEL

Sets the debug level within the underlying LDAP C lib.

ldap.OPT_DEFBASE
ldap.OPT_DEREF

Specifies how alias derefencing is done within the underlying LDAP C lib.

ldap.OPT_ERROR_STRING
ldap.OPT_DIAGNOSTIC_MESSAGE
ldap.OPT_HOST_NAME
ldap.OPT_MATCHED_DN
ldap.OPT_NETWORK_TIMEOUT
ldap.OPT_PROTOCOL_VERSION

Sets the LDAP protocol version used for a connection. This is mapped to object attribute ldap.LDAPObject.protocol_version

ldap.OPT_REFERRALS

int specifying whether referrals should be automatically chased within the underlying LDAP C lib.

ldap.OPT_REFHOPLIMIT
ldap.OPT_RESTART
ldap.OPT_SERVER_CONTROLS
ldap.OPT_SIZELIMIT
ldap.OPT_SUCCESS
ldap.OPT_TIMELIMIT
ldap.OPT_TIMEOUT
ldap.OPT_URI

SASL options

ldap.OPT_X_SASL_AUTHCID
ldap.OPT_X_SASL_AUTHZID
ldap.OPT_X_SASL_MECH
ldap.OPT_X_SASL_NOCANON

If set to zero SASL host name canonicalization is disabled.

ldap.OPT_X_SASL_REALM
ldap.OPT_X_SASL_SECPROPS
ldap.OPT_X_SASL_SSF
ldap.OPT_X_SASL_SSF_EXTERNAL
ldap.OPT_X_SASL_SSF_MAX
ldap.OPT_X_SASL_SSF_MIN

TLS options

ldap.OPT_X_TLS
ldap.OPT_X_TLS_ALLOW
ldap.OPT_X_TLS_CACERTDIR
ldap.OPT_X_TLS_CACERTFILE
ldap.OPT_X_TLS_CERTFILE
ldap.OPT_X_TLS_CIPHER_SUITE
ldap.OPT_X_TLS_CTX
ldap.OPT_X_TLS_DEMAND
ldap.OPT_X_TLS_HARD
ldap.OPT_X_TLS_KEYFILE
ldap.OPT_X_TLS_NEVER
ldap.OPT_X_TLS_RANDOM_FILE
ldap.OPT_X_TLS_REQUIRE_CERT
ldap.OPT_X_TLS_TRY

Keepalive options

ldap.OPT_X_KEEPALIVE_IDLE
ldap.OPT_X_KEEPALIVE_PROBES
ldap.OPT_X_KEEPALIVE_INTERVAL

DN format flags

This constants are used for DN-parsing functions found in sub-module ldap.dn.

See also

ldap_str2dn{3}

ldap.DN_FORMAT_LDAP
ldap.DN_FORMAT_LDAPV3
ldap.DN_FORMAT_LDAPV2
ldap.DN_FORMAT_DCE
ldap.DN_FORMAT_UFN
ldap.DN_FORMAT_AD_CANONICAL
ldap.DN_FORMAT_MASK
ldap.DN_PRETTY
ldap.DN_SKIP
ldap.DN_P_NOLEADTRAILSPACES
ldap.DN_P_NOSPACEAFTERRDN
ldap.DN_PEDANTIC

Exceptions

The module defines the following exceptions:

exception ldap.LDAPError

This is the base class of all execeptions raised by the module ldap. Unlike the C interface, errors are not returned as result codes, but are instead turned into exceptions, raised as soon an the error condition is detected.

The exceptions are accompanied by a dictionary possibly containing an string value for the key desc (giving an English description of the error class) and/or a string value for the key info (giving a string containing more information that the server may have sent).

A third possible field of this dictionary is matched and is set to a truncated form of the name provided or alias dereferenced for the lowest entry (object or alias) that was matched.

exception ldap.ADMINLIMIT_EXCEEDED
exception ldap.AFFECTS_MULTIPLE_DSAS
exception ldap.ALIAS_DEREF_PROBLEM

A problem was encountered when dereferencing an alias. (Sets the matched field.)

exception ldap.ALIAS_PROBLEM

An alias in the directory points to a nonexistent entry. (Sets the matched field.)

exception ldap.ALREADY_EXISTS

The entry already exists. E.g. the dn specified with add() already exists in the DIT.

exception ldap.AUTH_UNKNOWN

The authentication method specified to bind() is not known.

exception ldap.BUSY

The DSA is busy.

exception ldap.CLIENT_LOOP
exception ldap.COMPARE_FALSE

A compare operation returned false. (This exception should never be seen because compare() returns a boolean result.)

exception ldap.COMPARE_TRUE

A compare operation returned true. (This exception should never be seen because compare() returns a boolean result.)

exception ldap.CONFIDENTIALITY_REQUIRED

Indicates that the session is not protected by a protocol such as Transport Layer Security (TLS), which provides session confidentiality.

exception ldap.CONNECT_ERROR
exception ldap.CONSTRAINT_VIOLATION

An attribute value specified or an operation started violates some server-side constraint (e.g., a postalAddress has too many lines or a line that is too long or a password is expired).

exception ldap.CONTROL_NOT_FOUND
exception ldap.DECODING_ERROR

An error was encountered decoding a result from the LDAP server.

exception ldap.ENCODING_ERROR

An error was encountered encoding parameters to send to the LDAP server.

exception ldap.FILTER_ERROR

An invalid filter was supplied to search() (e.g. unbalanced parentheses).

exception ldap.INAPPROPRIATE_AUTH

Inappropriate authentication was specified (e.g. AUTH_SIMPLE was specified and the entry does not have a userPassword attribute).

exception ldap.INAPPROPRIATE_MATCHING

Filter type not supported for the specified attribute.

exception ldap.INSUFFICIENT_ACCESS

The user has insufficient access to perform the operation.

exception ldap.INVALID_CREDENTIALS

Invalid credentials were presented during bind() or simple_bind(). (e.g., the wrong password).

exception ldap.INVALID_DN_SYNTAX

A syntactically invalid DN was specified. (Sets the matched field.)

exception ldap.INVALID_SYNTAX

An attribute value specified by the client did not comply to the syntax defined in the server-side schema.

exception ldap.IS_LEAF

The object specified is a leaf of the diretcory tree. Sets the matched field of the exception dictionary value.

exception ldap.LOCAL_ERROR

Some local error occurred. This is usually due to failed memory allocation.

exception ldap.LOOP_DETECT

A loop was detected.

exception ldap.MORE_RESULTS_TO_RETURN
exception ldap.NAMING_VIOLATION

A naming violation occurred. This is raised e.g. if the LDAP server has constraints about the tree naming.

exception ldap.NO_OBJECT_CLASS_MODS

Modifying the objectClass attribute as requested is not allowed (e.g. modifying structural object class of existing entry).

exception ldap.NOT_ALLOWED_ON_NONLEAF

The operation is not allowed on a non-leaf object.

exception ldap.NOT_ALLOWED_ON_RDN

The operation is not allowed on an RDN.

exception ldap.NOT_SUPPORTED
exception ldap.NO_MEMORY
exception ldap.NO_OBJECT_CLASS_MODS

Object class modifications are not allowed.

exception ldap.NO_RESULTS_RETURNED
exception ldap.NO_SUCH_ATTRIBUTE

The attribute type specified does not exist in the entry.

exception ldap.NO_SUCH_OBJECT

The specified object does not exist in the directory. Sets the matched field of the exception dictionary value.

exception ldap.OBJECT_CLASS_VIOLATION

An object class violation occurred when the LDAP server checked the data sent by the client against the server-side schema (e.g. a “must” attribute was missing in the entry data).

exception ldap.OPERATIONS_ERROR

An operations error occurred.

exception ldap.OTHER

An unclassified error occurred.

exception ldap.PARAM_ERROR

An ldap routine was called with a bad parameter.

exception ldap.PARTIAL_RESULTS

Partial results only returned. This exception is raised if a referral is received when using LDAPv2. (This exception should never be seen with LDAPv3.)

exception ldap.PROTOCOL_ERROR

A violation of the LDAP protocol was detected.

exception ldap.RESULTS_TOO_LARGE

The result does not fit into a UDP packet. This happens only when using UDP-based CLDAP (connection-less LDAP) which is not supported anyway.

exception ldap.SASL_BIND_IN_PROGRESS
exception ldap.SERVER_DOWN

The LDAP library can’t contact the LDAP server.

exception ldap.SIZELIMIT_EXCEEDED

An LDAP size limit was exceeded. This could be due to a sizelimit configuration on the LDAP server.

exception ldap.STRONG_AUTH_NOT_SUPPORTED

The LDAP server does not support strong authentication.

exception ldap.STRONG_AUTH_REQUIRED

Strong authentication is required for the operation.

exception ldap.TIMELIMIT_EXCEEDED

An LDAP time limit was exceeded.

exception ldap.TIMEOUT

A timelimit was exceeded while waiting for a result from the server.

exception ldap.TYPE_OR_VALUE_EXISTS

An attribute type or attribute value specified already exists in the entry.

exception ldap.UNAVAILABLE

The DSA is unavailable.

exception ldap.UNAVAILABLE_CRITICAL_EXTENSION

Indicates that the LDAP server was unable to satisfy a request because one or more critical extensions were not available. Either the server does not support the control or the control is not appropriate for the operation type.

exception ldap.UNDEFINED_TYPE

An attribute type used is not defined in the server-side schema.

exception ldap.UNWILLING_TO_PERFORM

The DSA is unwilling to perform the operation.

exception ldap.USER_CANCELLED

The operation was cancelled via the abandon() method.

The above exceptions are raised when a result code from an underlying API call does not indicate success.

LDAPObject classes

class ldap.LDAPObject

Instances of LDAPObject are returned by initialize() and open() (deprecated). The connection is automatically unbound and closed when the LDAP object is deleted. Internally LDAPObject is set to SimpleLDAPObject by default.

class ldap.SimpleLDAPObject(uri[, trace_level=0[, trace_file=sys.stdout[, trace_stack_limit=5]]])

Instances of LDAPObject are returned by initialize() and open() (deprecated). The connection is automatically unbound and closed when the LDAP object is deleted.

class ldap.ReconnectLDAPObject(uri [, trace_level=0 [, trace_file=sys.stdout [, trace_stack_limit=5] [, retry_max=1 [, retry_delay=60.0]]]])

This class is derived from SimpleLDAPObject and used for automatic reconnects when using the synchronous request methods (see below). This class also implements the pickle protocol.

For automatic reconnects it has additional arguments:

retry_max specifies the number of reconnect attempts before re-raising the ldap.SERVER_DOWN exception.

retry_delay specifies the time in seconds between reconnect attempts.

Arguments for LDAPv3 controls

The ldap.controls module can be used for constructing and decoding LDAPv3 controls. These arguments are available in the methods with names ending in _ext or _ext_s:

serverctrls
is a list of ldap.controls.LDAPControl instances sent to the server along with the LDAP request (see module ldap.controls). These are controls which alter the behaviour of the server when processing the request if the control is supported by the server. The effect of controls might differ depending on the type of LDAP request or controls might not be applicable with certain LDAP requests at all.
clientctrls
is a list of ldap.controls.LDAPControl instances passed to the client API and alter the behaviour of the client when processing the request.

Sending LDAP requests

Most methods on LDAP objects initiate an asynchronous request to the LDAP server and return a message id that can be used later to retrieve the result with result().

Methods with names ending in _s are the synchronous form and wait for and return with the server’s result, or with None if no data is expected.

LDAPObject instances have the following methods:

LDAPObject.abandon(msgid) → None
LDAPObject.abandon_ext(msgid[, serverctrls=None[, clientctrls=None]]) → None

Abandons an LDAP operation in progress without waiting for a LDAP response. The msgid argument should be the message ID of an outstanding LDAP operation as returned by the asynchronous methods search(), modify(), etc. The caller can expect that the result of an abandoned operation will not be returned from a future call to result().

serverctrls and clientctrls like described above.

LDAPObject.add(dn, modlist) → int
LDAPObject.add_s(dn, modlist) → None
LDAPObject.add_ext(dn, modlist[, serverctrls=None[, clientctrls=None]]) → int
LDAPObject.add_ext_s(dn, modlist[, serverctrls=None[, clientctrls=None]]) → None

Performs an LDAP add operation. The dn argument is the distinguished name (DN) of the entry to add, and modlist is a list of attributes to be added. The modlist is similar the one passed to modify(), except that the operation integer is omitted from the tuples in modlist. You might want to look into sub-module refmodule{ldap.modlist} for generating the modlist.

The asynchronous methods add() and add_ext() return the message ID of the initiated request.

serverctrls and clientctrls like described above.

LDAPObject.bind(who, cred, method) → int
LDAPObject.bind_s(who, cred, method) → None
LDAPObject.simple_bind([who=''[, cred='']]) → int
LDAPObject.simple_bind_s([who=''[, cred='']]) → None

After an LDAP object is created, and before any other operations can be attempted over the connection, a bind operation must be performed.

This method attempts to bind with the LDAP server using either simple authentication, or Kerberos (if available). The first and most general method, bind(), takes a third parameter, method which can currently solely be AUTH_SIMPLE.

LDAPObject.sasl_interactive_bind_s(who, auth) → None

This call is used to bind to the directory with a SASL bind request.

LDAPObject.cancel(cancelid[, serverctrls=None[, clientctrls=None]]) → None

Send cancels extended operation for an LDAP operation specified by cancelid. The cancelid should be the message id of an outstanding LDAP operation as returned by the asynchronous methods search(), modify() etc. The caller can expect that the result of an abandoned operation will not be returned from a future call to result(). In opposite to abandon() this extended operation gets an result from the server and thus should be preferred if the server supports it.

serverctrls and clientctrls like described above.

RFC 3909 - Lightweight Directory Access Protocol (LDAP): Cancel Operation

LDAPObject.compare(dn, attr, value) → int
LDAPObject.compare_s(dn, attr, value) → tuple
LDAPObject.compare_ext(dn, attr, value[, serverctrls=None[, clientctrls=None]]) → int
LDAPObject.compare_ext_s(dn, attr, value[, serverctrls=None[, clientctrls=None]]) → tuple

Perform an LDAP comparison between the attribute named attr of entry dn, and the value value. The synchronous forms returns 0 for false, or 1 for true. The asynchronous forms returns the message ID of the initiated request, and the result of the asynchronous compare can be obtained using result().

Note that the asynchronous technique yields the answer by raising the exception objects ldap.COMPARE_TRUE or ldap.COMPARE_FALSE.

serverctrls and clientctrls like described above.

Note

A design fault in the LDAP API prevents value from containing NULL characters.

LDAPObject.delete(dn) → int
LDAPObject.delete_s(dn) → None
LDAPObject.delete_ext(dn[, serverctrls=None[, clientctrls=None]]) → int
LDAPObject.delete_ext_s(dn[, serverctrls=None[, clientctrls=None]]) → None

Performs an LDAP delete operation on dn. The asynchronous form returns the message id of the initiated request, and the result can be obtained from a subsequent call to result().

serverctrls and clientctrls like described above.

ldap.extop(extreq[,serverctrls=None[,clientctrls=None]]]) → int
ldap.extop_s(extreq[,serverctrls=None[,clientctrls=None[,extop_resp_class=None]]]]) -> (respoid,respvalue)

Performs an LDAP extended operation. The asynchronous form returns the message id of the initiated request, and the result can be obtained from a subsequent call to extop_result().

The extreq is an instance of class ldap.extop.ExtendedRequest containing the parameters for the extended operation request.

If argument extop_resp_class is set to a sub-class of ldap.extop.ExtendedResponse this class is used to return an object of this class instead of a raw BER value in respvalue.

ldap.extop_result(self, msgid=ldap.RES_ANY, all=1, timeout=None) -> (respoid, respvalue)

Wrapper method around result4() just for retrieving the result of an extended operation sent before.

LDAPObject.modify(dn, modlist) → int
LDAPObject.modify_s(dn, modlist) → None
LDAPObject.modify_ext(dn, modlist[, serverctrls=None[, clientctrls=None]]) → int
LDAPObject.modify_ext_s(dn, modlist[, serverctrls=None[, clientctrls=None]]) → None

Performs an LDAP modify operation on an entry’s attributes. The dn argument is the distinguished name (DN) of the entry to modify, and modlist is a list of modifications to make to that entry.

Each element in the list modlist should be a tuple of the form (mod_op,mod_type,mod_vals), where mod_op indicates the operation (one of ldap.MOD_ADD, ldap.MOD_DELETE, or ldap.MOD_REPLACE), mod_type is a string indicating the attribute type name, and mod_vals is either a string value or a list of string values to add, delete or replace respectively. For the delete operation, mod_vals may be None indicating that all attributes are to be deleted.

serverctrls and clientctrls like described above.

The asynchronous methods modify() and modify_ext() return the message ID of the initiated request.

You might want to look into sub-module ldap.modlist for generating modlist.

LDAPObject.modrdn(dn, newrdn[, delold=1]) → int
LDAPObject.modrdn_s(dn, newrdn[, delold=1]) → None

Perform a modify RDN operation, (i.e. a renaming operation). These routines take dn (the DN of the entry whose RDN is to be changed, and newrdn, the new RDN to give to the entry. The optional parameter delold is used to specify whether the old RDN should be kept as an attribute of the entry or not. The asynchronous version returns the initiated message id.

This operation is emulated by rename() and rename_s() methods since the modrdn2* routines in the C library are deprecated.

LDAPObject.passwd(user, oldpw, newpw[, serverctrls=None[, clientctrls=None]]) → int
LDAPObject.passwd_s(user, oldpw, newpw[, serverctrls=None[, clientctrls=None]]) → None

Perform a LDAP Password Modify Extended Operation operation on the entry specified by user. The old password in oldpw is replaced with the new password in newpw by a LDAP server supporting this operation.

If oldpw is not None it has to match the old password of the specified user which is sometimes used when a user changes his own password.

serverctrls and clientctrls like described above.

The asynchronous version returns the initiated message id.

See also

RFC 3062 - LDAP Password Modify Extended Operation

LDAPObject.rename(dn, newrdn[, newsuperior=None[, delold=1[, serverctrls=None[, clientctrls=None]]]]) → int
LDAPObject.rename_s(dn, newrdn[, newsuperior=None[, delold=1[, serverctrls=None[, clientctrls=None]]]]) → None

Perform a Rename operation, (i.e. a renaming operation). These routines take dn (the DN of the entry whose RDN is to be changed, and newrdn, the new RDN to give to the entry. The optional parameter newsuperior is used to specify a new parent DN for moving an entry in the tree (not all LDAP servers support this). The optional parameter delold is used to specify whether the old RDN should be kept as an attribute of the entry or not.

serverctrls and clientctrls like described above.

LDAPObject.result([msgid=RES_ANY[, all=1[, timeout=None]]]) → 2-tuple

This method is used to wait for and return the result of an operation previously initiated by one of the LDAP asynchronous operations (eg search(), modify(), etc.)

The msgid parameter is the integer identifier returned by that method. The identifier is guaranteed to be unique across an LDAP session, and tells the result() method to request the result of that specific operation.

If a result is desired from any one of the in-progress operations, msgid should be specified as the constant RES_ANY and the method result2() should be used instead.

The all parameter only has meaning for search() responses and is used to select whether a single entry of the search response should be returned, or to wait for all the results of the search before returning.

A search response is made up of zero or more search entries followed by a search result. If all is 0, search entries will be returned one at a time as they come in, via separate calls to result(). If all is 1, the search response will be returned in its entirety, i.e. after all entries and the final search result have been received.

For all set to 0, result tuples trickle in (with the same message id), and with the result types RES_SEARCH_ENTRY and RES_SEARCH_REFERENCE, until the final result which has a result type of RES_SEARCH_RESULT and a (usually) empty data field. When all is set to 1, only one result is returned, with a result type of RES_SEARCH_RESULT, and all the result tuples listed in the data field.

The timeout parameter is a limit on the number of seconds that the method will wait for a response from the server. If timeout is negative (which is the default), the method will wait indefinitely for a response. The timeout can be expressed as a floating-point value, and a value of 0 effects a poll. If a timeout does occur, a ldap.TIMEOUT exception is raised, unless polling, in which case (None, None) is returned.

The result() method returns a tuple of the form (result-type, result-data). The first element, result-type is a string, being one of these module constants: RES_BIND, RES_SEARCH_ENTRY, RES_SEARCH_REFERENCE, RES_SEARCH_RESULT, RES_MODIFY, RES_ADD, RES_DELETE, RES_MODRDN, or RES_COMPARE.

If all is 0, one response at a time is returned on each call to result(), with termination indicated by result-data being an empty list.

See search() for a description of the search result’s result-data, otherwise the result-data is normally meaningless.

LDAPObject.result2([msgid=RES_ANY[, all=1[, timeout=None]]]) → 3-tuple

This method behaves almost exactly like result(). But it returns a 3-tuple also containing the message id of the outstanding LDAP operation a particular result message belongs to. This is especially handy if one needs to dispatch results obtained with msgid=RES_ANY to several consumer threads which invoked a particular LDAP operation.

LDAPObject.result3([msgid=RES_ANY[, all=1[, timeout=None]]]) → 4-tuple

This method behaves almost exactly like result2(). But it returns an extra item in the tuple, the decoded server controls.

LDAPObject.result4([msgid=RES_ANY[, all=1[, timeout=None[, add_ctrls=0[, add_intermediates=0[, add_extop=0[, resp_ctrl_classes=None]]]]]]]) → 6-tuple

This method behaves almost exactly like result3(). But it returns an extra items in the tuple, the decoded results of an extended response.

The additional arguments are:

add_ctrls (integer flag) specifies whether response controls are returned.

add_intermediates (integer flag) specifies whether response controls of intermediate search results are returned.

add_extop (integer flag) specifies whether the response of an extended operation is returned. If using extended operations you should consider using the method extop_result() or extop_s() instead.

resp_ctrl_classes is a dictionary mapping the OID of a response controls to a ldap.controls.ResponseControl class of response controls known by the application. So the response control value will be automatically decoded. If None the global dictionary ldap.controls.KNOWN_RESPONSE_CONTROLS is used instead.

LDAPObject.search(base, scope[, filterstr='(objectClass=*)'[, attrlist=None[, attrsonly=0]]]) → int
LDAPObject.search_s(base, scope[, filterstr='(objectClass=*)'[, attrlist=None[, attrsonly=0]]]) → list|None
LDAPObject.search_st(base, scope[, filterstr='(objectClass=*)'[, attrlist=None[, attrsonly=0[, timeout=-1]]]]) → list|None
LDAPObject.search_ext(base, scope[, filterstr='(objectClass=*)'[, attrlist=None[, attrsonly=0[, serverctrls=None[, clientctrls=None[, timeout=-1[, sizelimit=0]]]]]]]) → int
LDAPObject.search_ext_s(base, scope[, filterstr='(objectClass=*)'[, attrlist=None[, attrsonly=0[, serverctrls=None[, clientctrls=None[, timeout=-1[, sizelimit=0]]]]]]]) → list|None

Perform an LDAP search operation, with base as the DN of the entry at which to start the search, scope being one of SCOPE_BASE (to search the object itself), SCOPE_ONELEVEL (to search the object’s immediate children), or SCOPE_SUBTREE (to search the object and all its descendants).

The filterstr argument is a string representation of the filter to apply in the search.

See also

RFC 4515 - Lightweight Directory Access Protocol (LDAP): String Representation of Search Filters.

Each result tuple is of the form (dn, attrs), where dn is a string containing the DN (distinguished name) of the entry, and attrs is a dictionary containing the attributes associated with the entry. The keys of attrs are strings, and the associated values are lists of strings.

The DN in dn is automatically extracted using the underlying libldap function ldap_get_dn(), which may raise an exception if the DN is malformed.

If attrsonly is non-zero, the values of attrs will be meaningless (they are not transmitted in the result).

The retrieved attributes can be limited with the attrlist parameter. If attrlist is None, all the attributes of each entry are returned.

serverctrls and clientctrls like described above.

The synchronous form with timeout, search_st() or search_ext_s(), will block for at most timeout seconds (or indefinitely if timeout is negative). A ldap.TIMEOUT exception is raised if no result is received within the specified time.

The amount of search results retrieved can be limited with the sizelimit parameter when using search_ext() or search_ext_s() (client-side search limit). If non-zero not more than sizelimit results are returned by the server.

LDAPObject.start_tls_s() → None
Negotiate TLS with server. The version attribute must have been set to VERSION3 (which it is by default) before calling this method. If TLS could not be started an exception will be raised.

See also

RFC 2830 - Lightweight Directory Access Protocol (v3): Extension for Transport Layer Security

LDAPObject.unbind() → int
LDAPObject.unbind_s() → None
LDAPObject.unbind_ext([serverctrls=None[, clientctrls=None]]) → int
LDAPObject.unbind_ext_s([serverctrls=None[, clientctrls=None]]) → None

This call is used to unbind from the directory, terminate the current association, and free resources. Once called, the connection to the LDAP server is closed and the LDAP object is marked invalid. Further invocation of methods on the object will yield exceptions.

serverctrls and clientctrls like described above.

These methods are all synchronous in nature.

LDAPObject.whoami_s() → string

This synchronous method implements the LDAP “Who Am I?” extended operation.

It is useful for finding out to find out which identity is assumed by the LDAP server after a SASL bind.

See also

RFC 4532 - Lightweight Directory Access Protocol (LDAP) “Who am I?” Operation

Connection-specific LDAP options

LDAPObject.get_option(option) → int|string

This method returns the value of the LDAPObject option specified by option.

LDAPObject.set_option(option, invalue) → None

This method sets the value of the LDAPObject option specified by option to invalue.

Object attributes

If the underlying library provides enough information, each LDAP object will also have the following attributes. These attributes are mutable unless described as read-only.

LDAPObject.deref -> int

Controls whether aliases are automatically dereferenced. This must be one of DEREF_NEVER, DEREF_SEARCHING, DEREF_FINDING or DEREF_ALWAYS. This option is mapped to option constant OPT_DEREF and used in the underlying OpenLDAP client lib.

LDAPObject.network_timeout -> int

Limit on waiting for a network response, in seconds. Defaults to NO_LIMIT. This option is mapped to option constant OPT_NETWORK_TIMEOUT and used in the underlying OpenLDAP client lib.

LDAPObject.protocol_version -> int

Version of LDAP in use (either VERSION2 for LDAPv2 or VERSION3 for LDAPv3). This option is mapped to option constant OPT_PROTOCOL_VERSION and used in the underlying OpenLDAP client lib.

Note

It is highly recommended to set the protocol version after establishing a LDAP connection with ldap.initialize() and before submitting the first request.

LDAPObject.sizelimit -> int

Limit on size of message to receive from server. Defaults to NO_LIMIT. This option is mapped to option constant OPT_SIZELIMIT and used in the underlying OpenLDAP client lib. Its use is deprecated in favour of sizelimit parameter when using search_ext().

LDAPObject.timelimit -> int

Limit on waiting for any response, in seconds. Defaults to NO_LIMIT. This option is mapped to option constant OPT_TIMELIMIT and used in the underlying OpenLDAP client lib. Its use is deprecated in favour of using timeout.

LDAPObject.timeout -> int

Limit on waiting for any response, in seconds. Defaults to NO_LIMIT. This option is used in the wrapper module.

Example

The following example demonstrates how to open a connection to an LDAP server using the ldap module and invoke a synchronous subtree search.

>>> import ldap
>>> l = ldap.initialize('ldap://localhost:1390')
>>> l.search_s('ou=Testing,dc=stroeder,dc=de',ldap.SCOPE_SUBTREE,'(cn=fred*)',['cn','mail'])
[('cn=Fred Feuerstein,ou=Testing,dc=stroeder,dc=de', {'cn': ['Fred Feuerstein']})]
>>> r = l.search_s('ou=Testing,dc=stroeder,dc=de',ldap.SCOPE_SUBTREE,'(objectClass=*)',['cn','mail'])
>>> for dn,entry in r:
>>>   print 'Processing',repr(dn)
>>>   handle_ldap_entry(entry)