ldap3.core.connection module

class ldap3.core.connection.Connection(server, user=None, password=None, auto_bind='DEFAULT', version=3, authentication=None, client_strategy='SYNC', auto_referrals=True, auto_range=True, sasl_mechanism=None, sasl_credentials=None, check_names=True, collect_usage=False, read_only=False, lazy=False, raise_exceptions=False, pool_name=None, pool_size=None, pool_lifetime=None, fast_decoder=True, receive_timeout=None, return_empty_attributes=True, use_referral_cache=False, auto_escape=True, auto_encode=True, pool_keepalive=None)

Bases: object

Main ldap connection class.

Controls, if used, must be a list of tuples. Each tuple must have 3 elements, the control OID, a boolean meaning if the control is critical, a value.

If the boolean is set to True the server must honor the control or refuse the operation

Mixing controls must be defined in controls specification (as per RFC 4511)

  • server (Server, str) – the Server object to connect to
  • user (str) – the user name for simple authentication
  • password (str) – the password for simple authentication
  • auto_bind (int, can be one of AUTO_BIND_DEFAULT, AUTO_BIND_NONE, AUTO_BIND_NO_TLS, AUTO_BIND_TLS_BEFORE_BIND, AUTO_BIND_TLS_AFTER_BIND as specified in ldap3) – specify if the bind will be performed automatically when defining the Connection object
  • version (int) – LDAP version, default to 3
  • authentication (int, can be one of AUTH_ANONYMOUS, AUTH_SIMPLE or AUTH_SASL, as specified in ldap3) – type of authentication
  • client_strategy (can be one of STRATEGY_SYNC, STRATEGY_ASYNC_THREADED, STRATEGY_LDIF_PRODUCER, STRATEGY_SYNC_RESTARTABLE, STRATEGY_REUSABLE_THREADED as specified in ldap3) – communication strategy used in the Connection
  • auto_referrals (bool) – specify if the connection object must automatically follow referrals
  • sasl_mechanism (str) – mechanism for SASL authentication, can be one of ‘EXTERNAL’, ‘DIGEST-MD5’, ‘GSSAPI’, ‘PLAIN’
  • sasl_credentials (tuple) – credentials for SASL mechanism
  • check_names (bool) – if True the library will check names of attributes and object classes against the schema. Also values found in entries will be formatted as indicated by the schema
  • collect_usage (bool) – collect usage metrics in the usage attribute
  • read_only (bool) – disable operations that modify data in the LDAP server
  • lazy (bool) – open and bind the connection only when an actual operation is performed
  • raise_exceptions (bool) – raise exceptions when operations are not successful, if False operations return False if not successful but not raise exceptions
  • pool_name (str) – pool name for pooled strategies
  • pool_size (int) – pool size for pooled strategies
  • pool_lifetime (int) – pool lifetime for pooled strategies
  • use_referral_cache (bool) – keep referral connections open and reuse them
  • auto_escape – automatic escaping of filter values
  • auto_encode – automatic encoding of attribute values
abandon(message_id, controls=None)

Abandon the operation indicated by message_id

add(dn, object_class=None, attributes=None, controls=None)

Add dn to the DIT, object_class is None, a class name or a list of class names.

Attributes is a dictionary in the form ‘attr’: ‘val’ or ‘attr’: [‘val1’, ‘val2’, …] for multivalued attributes

bind(read_server_info=True, controls=None)

Bind to ldap Server with the authentication method and the user defined in the connection

  • read_server_info – reads info from server
  • controls (list of tuple) – LDAP controls to send along with the bind operation


compare(dn, attribute, value, controls=None)

Perform a compare operation

delete(dn, controls=None)

Delete the entry identified by the DN from the DIB.

extended(request_name, request_value=None, controls=None, no_encode=None)

Performs an extended operation

modify(dn, changes, controls=None)

Modify attributes of entry

  • changes is a dictionary in the form {‘attribute1’: change), ‘attribute2’: [change, change, …], …}
  • change is (operation, [value1, value2, …])
modify_dn(dn, relative_dn, delete_old_dn=True, new_superior=None, controls=None)

Modify DN of the entry or performs a move of the entry in the DIT.

rebind(user=None, password=None, authentication=None, sasl_mechanism=None, sasl_credentials=None, read_server_info=True, controls=None)
response_to_file(target, raw=False, indent=4, sort=True)
response_to_json(raw=False, search_result=None, indent=4, sort=True, stream=None, checked_attributes=True, include_empty=True)
response_to_ldif(search_result=None, all_base64=False, line_separator=None, sort_order=None, stream=None)
search(search_base, search_filter, search_scope='SUBTREE', dereference_aliases='ALWAYS', attributes=None, size_limit=0, time_limit=0, types_only=False, get_operational_attributes=False, controls=None, paged_size=None, paged_criticality=False, paged_cookie=None, auto_escape=None)

Perform an ldap search:

  • If attributes is empty noRFC2696 with the specified size
  • If paged is 0 and cookie is present the search is abandoned on server attribute is returned
  • If attributes is ALL_ATTRIBUTES all attributes are returned
  • If paged_size is an int greater than 0 a simple paged search is tried as described in
  • Cookie is an opaque string received in the last paged search and must be used on the next paged search response
  • If lazy == True open and bind will be deferred until another LDAP operation is performed
  • If mssing_attributes == True then an attribute not returned by the server is set to None
  • If auto_escape is set it overrides the Connection auto_escape

Used by the LDIFProducer strategy to accumulate the ldif-change operations with a single LDIF header :return: reference to the response stream if defined in the strategy.


Unbind the connected user. Unbind implies closing session as per RFC4511 (4.3)

Parameters:controls – LDAP controls to send along with the bind operation

Usage statistics for the connection. :return: Usage object