LDAPObject classes

class LDAPObject

Instances of the class LDAPObject are created either by calling the function ldap_initialize(), or by calling the LDAP class constructor. The two methods are stricly equivalent. More precisely,

>>> l = ldap_initialize('ldap://host.test')

is equivalent to:

>>> l = LDAP('ldap://host.test')

The connection is automatically unbound and closed when the LDAP object is deleted.

class LDAP(uri[, version=LDAP_VERSION3])

An instance of the class LDAPObject has the following attributes:

uri

LDAP URI (Uniform Resource Identifier): ldap[is]://host[:port]

scheme

URI scheme: ldap, ldapi or ldaps

host

LDAP host to contact

ip

IPv4/v6 address of LDAP host to contact

port

port on host (usually 389 or 636)

dn

To learn how dn attribute is used, refer to the documentation of the function ldap_initialize(). This attribute can be modified at any time:

>>> l = ldap_initialize('ldap://host.test')
>>> print(l.dn)
None
>>> l.dn = 'dc=example,dc=test'
>>> print(l.dn)
dc=example,dc=test
>>> l.dn = None

Methods of the class LDAPObject are:

simple_bind_s([user, password])

Just after an LDAPObject is created, it must be bound. If parameters user and password are not present, an anonymous bind is done

Parameters:
  • user (str) – DN to bind as
  • password (str) – userPassword associated with the entry
Returns:

None

Raises:

LDAPError

See also

ldap_simple_bind_s(3)

bind_s([user, password, method=LDAP_AUTH_SIMPLE])

Identical to method simple_bind_s() except for the extra method parameter selecting the authentication method to use. Only method LDAP_AUTH_SIMPLE is currently available

Parameters:
  • user (str) – DN to bind as
  • password (str) – userPassword associated with the entry
  • method (int) – authentication method to use
Returns:

None

Raises:

LDAPError

See also

ldap_bind_s(3)

sasl_bind_s([mech[, dn[, password]]])

Performs a SASL bind

Parameters:
  • mech (str) – a SASL mechanism. For example: 'DIGEST-MD5', 'GSSAPI',... Default is LDAP_SASL_SIMPLE
  • dn (str) – the DN to bind as. If not provided, sasl_bind_s() will prompt for it.
  • password (str) – the password associated to entry dn. If not provided, sasl_bind_s() will prompt for it.
Returns:

None

Raises:

LDAPError, TypeError

>>> l = ldap_initialize('ldap://host.test')
>>> l.start_tls_s()
>>> l.sasl_bind_s(dn='uid=testsasl,ou=users,dc=example,dc=test')
Enter password:
>>>

See also

ldap_sasl_bind_s(3)

sasl_interactive_bind_s([mechs[, flags[, user[, password]]]])

Performs a (interactive) SASL bind

Parameters:
  • mechs – a list or a tuple of candidate mechanisms to use. For example: ('LOGIN', 'PLAIN', 'DIGEST-MD5')
  • flags (int) – controls the interaction used to retrieve any necessary SASL authentication parameters. Default flags is LDAP_SASL_INTERACTIVE if user or password is not provided and LDAP_SASL_QUIET otherwise. See SASL constants for available flags
  • user (str) – the user to authenticate. If not provided, sasl_interactive_bind_s() will prompt for it.
  • password (str) – the password for the provided user. If not given, sasl_interactive_bind_s() will prompt for it.
Returns:

None

Raises:

LDAPError, TypeError

>>> l = ldap_initialize('ldap://host.test')
>>> l.start_tls_s()
>>> l.sasl_interactive_bind_s(user='testsasl')
SASL/DIGEST-MD5 authentication started
Enter user's password:
SASL username: testsasl
SASL SSF: 128
SASL data security layer installed.
>>>

Another example:

>>> l.sasl_interactive_bind_s(mechs=('DIGEST-MD5',), flags=LDAP_SASL_QUIET, user='testsasl')
Enter user's password:
>>>

See also

ldap_sasl_interactive_bind_s(3)

unbind_s()

Unbind from the directory, terminate the current association, and free the resources previously allocated. Further invocation of methods on the object will yield exception LDAPError

Returns:None
Raises:LDAPError

See also

ldap_unbind_s(3)

start_tls_s()

Initiates TLS processing on an LDAP session

Returns:None
Raises:LDAPError

See also

ldap_start_tls_s(3)

get_option(option)

This routine is used to retreive options from an LDAPObject. See Options for available options.

Parameters:option (int) – global option to retreive
Returns:option value
Return type:int
Raises:LDAPError

See also

ldap_get_option(3)

set_option(option, optval)

This routine permits to set options for an LDAPObject. See Options for available options.

Parameters:
  • option (int) – option to set
  • optval (int) – option value
Returns:

None

Raises:

LDAPError

See also

ldap_set_option(3)

add_ext_s(dn, mods[, serverctrls[, clientctrls]])

Performs an LDAP add operation

Parameters:
Returns:

None

Raises:

LDAPError, TypeError

See also

ldap_add_ext_s(3)

delete_ext_s(dn[, serverctrls[, clientctrls]])

Performs an LDAP delete operation

Parameters:
Returns:

None

Raises:

LDAPError

See also

ldap_delete_ext_s(3)

modify_ext_s(dn, mods[, serverctrls[, clientctrls]])

Performs an LDAP modify operation

Parameters:
  • dn (str) – the DN of the entry to modify
  • mods – a list of LDAPMod objects. All modifications are performed in the order in which they are listed
  • serverctrls (LDAPControls) – specifies server control(s). See section Control methods
  • clientctrls (LDAPControls) – specifies client control(s). See section Control methods
Returns:

None

Raises:

LDAPError, TypeError

>>> l = ldap_initialize('ldap://host.test/dc=example,dc=test')
>>> l.start_tls_s()
>>> l.simple_bind_s(user='cn=admin', password='secret')
>>> lma = LDAPMod(LDAP_MOD_ADD, 'mailalias', ['bob@example.test'])
>>> lmr = LDAPMod(LDAP_MOD_REPLACE, 'givenName', ['Robert'])
>>> l.modify_ext_s('uid=bob,ou=users', [lma, lmr])

See also

ldap_modify_ext_s(3)

search_ext_s([base[, scope[, filter[, attrs[, attrsonly[, serverctrls[, clientctrls[, limit[, timeout]]]]]]]]])

Performs a LDAP search operation

Parameters:
  • base (str) – DN of the entry at which to start the search. If parameter base is not present, attribute dn is used if it’s not None otherwise exception LDAPError is raised
  • scope (int) – scope of the search. Default is LDAP_SCOPE_SUBTREE (search the object and all its descendants). For other possible values, see scope constants
  • filter (str) – filter to apply in the search. Default is ‘(objectClass=*)’
  • attrs (list of str(s)) – a list of attribute descriptions to return from matching entries. If parameter attrs is not present, all attributes are returned
  • attrsonly (bool) – if True, only attribute descriptions are returned (attribute values are then empty lists). Default is False
  • serverctrls (LDAPControls) – specifies server control(s). See section Control methods
  • clientctrls (LDAPControls) – specifies client control(s). See section Control methods
  • limit (int) – size limit of the answer. Default is LDAP_NO_LIMIT
  • timeout (int) – timeout in seconds to wait server answer. 0 means no timeout, this is the default
Returns:

a (possibly empty) list of results of the form: [(dn, entry), ...]. Each item of the list is 2-tuple where dn is a string containing the DN of the entry, and entry is a dictionary containing the attributes associated with the entry: {attr: [value, ...], ...}. For each entry in the dictionary, the key attr (string) is the attribute description and the corresponding value is the list of the associated values (strings)

Raises:

LDAPError, TypeError

A simple example:

>>> l = ldap_initialize('ldap://host.test/dc=example,dc=test')
>>> l.start_tls_s()
>>> l.simple_bind_s()
>>> l.search_ext_s(attrs=['uid'])
[('uid=alice',ou=users,dc=example,dc=test', {'uid': ['alice']}), ('uid=bob,ou=users,dc=example,dc=test', {'uid': ['bob']})]

See also

ldap_search_ext_s(3)

get_schema()

retreives LDAP schema from server

Returns:[(‘cn=Subschema’, entry)]
Raises:LDAPError, TypeError

More precisely, this function first executes the following statement:

>>> schema = self.search_ext_s(LDAP_SCHEMA_BASE, scope=LDAP_SCOPE_BASE, attrs=['+'])

The variable schema has the following form: [(‘cn=Subschema’, entry)]. The function get_schema(), before returning schema, performs the following treatment: fields ldapSyntaxes, matchingRules, matchingRuleUse, attributeTypes and objectClasses of dictionary entry are respectively parsed with ldap_str2syntax(), ldap_str2matchingrule(), ldap_str2matchingruleuse(), ldap_str2attributetype() and ldap_str2objectclass(). See section Schema parsing functions for more details

modrdn2_s(dn, newrdn[, deleteoldrdn=False])

performs an LDAP modify RDN operation

Parameters:
  • dn (str) – the DN of the entry whose RDN is to be changed
  • newrdn (str) – the new RDN
  • deleteoldrdn (bool) – if True, the old RDN values are deleted from the entry
Returns:

None

Raises:

LDAPError

See also

ldap_modrdn2_s(3)

Control methods

create_sort_control(keylist[, iscritical=False])

builds a sort control

Parameters:
  • keylist (str) – sort string. For example, if keylist is ‘sn -givenName’ the search results are sorted first by surname and then by given name, with the given name being sorted in reverse (descending order) as specified by the prefixed minus sign (-)
  • iscritical (bool) – the iscritical parameter is True non-zero for a critical control, False otherwise. Default is False
Returns:

a new LDAPControl object

Raises:

LDAPError, TypeError

create_assertion_control(filter[, iscritical=False])

builds an assertion control

Parameters:
  • filter (str) – control value (LDAP filter). See RFC 4528
  • iscritical (bool) – the iscritical parameter is True non-zero for a critical control, False otherwise. Default is False
Returns:

a new LDAPControl object

Raises:

LDAPError, TypeError