LDAPObject classes¶
-
class
LDAPObject
¶ Instances of the class
LDAPObject
are created either by calling the function ldap_initialize(), or by calling theLDAP
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
orldaps
-
host
¶ LDAP host to contact
-
ip
¶ IPv4/v6 address of LDAP host to contact
-
port
¶ port on host (usually
389
or636
)
-
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 doneParameters: - 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 methodLDAP_AUTH_SIMPLE
is currently availableParameters: - 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 isLDAP_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)
- mech (str) – a SASL mechanism. For example:
-
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
isLDAP_SASL_INTERACTIVE
ifuser
orpassword
is not provided andLDAP_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)
- mechs – a list or a tuple of candidate mechanisms to use. For
example:
-
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: - dn (str) – the DN of the entry to add
- mods – a list of LDAPMod
objects. Attribute
mode
of each LDAPMod object must beLDAP_MOD_ADD
- 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
See also
ldap_add_ext_s(3)
-
delete_ext_s
(dn[, serverctrls[, clientctrls]])¶ Performs an LDAP delete operation
Parameters: - dn (str) – the DN of the entry to be deleted
- serverctrls (
LDAPControls
) – specifies server control(s). See section Control methods - clientctrls (
LDAPControls
) – specifies client control(s). See section Control methods
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 exceptionLDAPError
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 isFalse
- 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)
- 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
-
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: fieldsldapSyntaxes
,matchingRules
,matchingRuleUse
,attributeTypes
andobjectClasses
of dictionary entry are respectively parsed withldap_str2syntax()
,ldap_str2matchingrule()
,ldap_str2matchingruleuse()
,ldap_str2attributetype()
andldap_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 isFalse
Returns: a new
LDAPControl
objectRaises: 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 isFalse
Returns: a new
LDAPControl
objectRaises: LDAPError
,TypeError
-