ldap3.core.connection module

class ldap3.core.connection.Connection(server, user=None, password=None, auto_bind='NONE', 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)

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)

Parameters:
  • 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_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

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

bool

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

Perform a compare operation

delete(dn, controls=None)

Delete the entry identified by the DN from the DIB.

do_ntlm_bind(controls)
do_sasl_bind(controls)
entries
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, ...])
  • operation is 0 (MODIFY_ADD), 1 (MODIFY_DELETE), 2 (MODIFY_REPLACE), 3 (MODIFY_INCREMENT)
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)
refresh_server_info()
repr_with_sensitive_data_stripped()
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 no 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 RFC2696 with the specified size
  • If paged is 0 and cookie is present the search is abandoned on server
  • 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
start_tls(read_server_info=True)
stream

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(controls=None)

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

Usage statistics for the connection. :return: Usage object