1126 lines
37 KiB
ReStructuredText
1126 lines
37 KiB
ReStructuredText
.. % $Id: ldap.rst,v 1.28 2015/06/05 20:49:04 stroeder Exp $
|
|
|
|
********************************************
|
|
:py:mod:`ldap` LDAP library interface module
|
|
********************************************
|
|
|
|
.. py:module:: ldap
|
|
:platform: Posix, Windows
|
|
:synopsis: Access to an underlying LDAP C library.
|
|
.. moduleauthor:: python-ldap project (see http://www.python-ldap.org/)
|
|
|
|
|
|
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 |release|. Source
|
|
and binaries are available from http://www.python-ldap.org/.
|
|
|
|
|
|
Functions
|
|
=========
|
|
|
|
This module defines the following functions:
|
|
|
|
.. py:function:: 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 :ref:`ldap-objects`) 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
|
|
:py:const:`0` for no logging,
|
|
:py:const:`1` for only logging the method calls with arguments,
|
|
:py:const:`2` for logging the method calls with arguments and the complete results and
|
|
:py:const:`9` for also logging the traceback of method calls.
|
|
|
|
.. seealso::
|
|
|
|
:rfc:`4516` - Lightweight Directory Access Protocol (LDAP): Uniform Resource Locator
|
|
|
|
.. py:function:: open(host [, port=PORT]) -> LDAPObject object
|
|
|
|
Opens a new connection with an LDAP server, and return an LDAP object (see
|
|
:ref:`ldap-objects`) 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.
|
|
|
|
|
|
.. py:function:: get_option(option) -> int|string
|
|
|
|
This function returns the value of the global option specified by *option*.
|
|
|
|
|
|
.. py:function:: set_option(option, invalue) -> None
|
|
|
|
This function sets the value of the global option specified by *option* to
|
|
*invalue*.
|
|
|
|
|
|
.. _ldap-constants:
|
|
|
|
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
|
|
-------
|
|
|
|
.. py:data:: PORT
|
|
|
|
The assigned TCP port number (389) that LDAP servers listen on.
|
|
|
|
.. py:data:: SASL_AVAIL
|
|
|
|
Integer where a non-zero value indicates that python-ldap was built with
|
|
support for SASL (Cyrus-SASL).
|
|
|
|
.. py:data:: TLS_AVAIL
|
|
|
|
Integer where a non-zero value indicates that python-ldap was built with
|
|
support for SSL/TLS (OpenSSL or similar libs).
|
|
|
|
|
|
.. _ldap-options:
|
|
|
|
Options
|
|
-------
|
|
|
|
.. seealso::
|
|
|
|
:manpage:`ldap.conf{5}` and :manpage:`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:
|
|
|
|
.. py:data:: OPT_API_FEATURE_INFO
|
|
|
|
.. py:data:: OPT_API_INFO
|
|
|
|
.. py:data:: OPT_CLIENT_CONTROLS
|
|
|
|
.. py:data:: OPT_DEBUG_LEVEL
|
|
|
|
Sets the debug level within the underlying LDAP C lib.
|
|
|
|
.. py:data:: OPT_DEFBASE
|
|
|
|
.. py:data:: OPT_DEREF
|
|
|
|
Specifies how alias derefencing is done within the underlying LDAP C lib.
|
|
|
|
.. py:data:: OPT_ERROR_STRING
|
|
|
|
.. py:data:: OPT_DIAGNOSTIC_MESSAGE
|
|
|
|
.. py:data:: OPT_HOST_NAME
|
|
|
|
.. py:data:: OPT_MATCHED_DN
|
|
|
|
.. py:data:: OPT_NETWORK_TIMEOUT
|
|
|
|
.. py:data:: OPT_PROTOCOL_VERSION
|
|
|
|
Sets the LDAP protocol version used for a connection. This is mapped to
|
|
object attribute `ldap.LDAPObject.protocol_version`
|
|
|
|
.. py:data:: OPT_REFERRALS
|
|
|
|
int specifying whether referrals should be automatically chased within
|
|
the underlying LDAP C lib.
|
|
|
|
.. py:data:: OPT_REFHOPLIMIT
|
|
|
|
.. py:data:: OPT_RESTART
|
|
|
|
.. py:data:: OPT_SERVER_CONTROLS
|
|
|
|
.. py:data:: OPT_SIZELIMIT
|
|
|
|
.. py:data:: OPT_SUCCESS
|
|
|
|
.. py:data:: OPT_TIMELIMIT
|
|
|
|
.. py:data:: OPT_TIMEOUT
|
|
|
|
.. py:data:: OPT_URI
|
|
|
|
.. _ldap-sasl-options:
|
|
|
|
SASL options
|
|
::::::::::::
|
|
|
|
.. py:data:: OPT_X_SASL_AUTHCID
|
|
|
|
.. py:data:: OPT_X_SASL_AUTHZID
|
|
|
|
.. py:data:: OPT_X_SASL_MECH
|
|
|
|
.. py:data:: OPT_X_SASL_NOCANON
|
|
|
|
If set to zero SASL host name canonicalization is disabled.
|
|
|
|
.. py:data:: OPT_X_SASL_REALM
|
|
|
|
.. py:data:: OPT_X_SASL_SECPROPS
|
|
|
|
.. py:data:: OPT_X_SASL_SSF
|
|
|
|
.. py:data:: OPT_X_SASL_SSF_EXTERNAL
|
|
|
|
.. py:data:: OPT_X_SASL_SSF_MAX
|
|
|
|
.. py:data:: OPT_X_SASL_SSF_MIN
|
|
|
|
.. _ldap-tls-options:
|
|
|
|
TLS options
|
|
:::::::::::
|
|
|
|
.. py:data:: OPT_X_TLS
|
|
|
|
.. py:data:: OPT_X_TLS_ALLOW
|
|
|
|
.. py:data:: OPT_X_TLS_CACERTDIR
|
|
|
|
.. py:data:: OPT_X_TLS_CACERTFILE
|
|
|
|
.. py:data:: OPT_X_TLS_CERTFILE
|
|
|
|
.. py:data:: OPT_X_TLS_CIPHER_SUITE
|
|
|
|
.. py:data:: OPT_X_TLS_CTX
|
|
|
|
.. py:data:: OPT_X_TLS_DEMAND
|
|
|
|
.. py:data:: OPT_X_TLS_HARD
|
|
|
|
.. py:data:: OPT_X_TLS_KEYFILE
|
|
|
|
.. py:data:: OPT_X_TLS_NEVER
|
|
|
|
.. py:data:: OPT_X_TLS_RANDOM_FILE
|
|
|
|
.. py:data:: OPT_X_TLS_REQUIRE_CERT
|
|
|
|
.. py:data:: OPT_X_TLS_TRY
|
|
|
|
.. _ldap-keepalive-options:
|
|
|
|
Keepalive options
|
|
:::::::::::::::::
|
|
|
|
.. py:data:: OPT_X_KEEPALIVE_IDLE
|
|
|
|
.. py:data:: OPT_X_KEEPALIVE_PROBES
|
|
|
|
.. py:data:: OPT_X_KEEPALIVE_INTERVAL
|
|
|
|
.. _ldap-dn-flags:
|
|
|
|
DN format flags
|
|
----------------
|
|
|
|
This constants are used for DN-parsing functions found in
|
|
sub-module :py:mod:`ldap.dn`.
|
|
|
|
.. seealso::
|
|
|
|
:manpage:`ldap_str2dn{3}`
|
|
|
|
|
|
.. py:data:: DN_FORMAT_LDAP
|
|
|
|
.. py:data:: DN_FORMAT_LDAPV3
|
|
|
|
.. py:data:: DN_FORMAT_LDAPV2
|
|
|
|
.. py:data:: DN_FORMAT_DCE
|
|
|
|
.. py:data:: DN_FORMAT_UFN
|
|
|
|
.. py:data:: DN_FORMAT_AD_CANONICAL
|
|
|
|
.. py:data:: DN_FORMAT_MASK
|
|
|
|
.. py:data:: DN_PRETTY
|
|
|
|
.. py:data:: DN_SKIP
|
|
|
|
.. py:data:: DN_P_NOLEADTRAILSPACES
|
|
|
|
.. py:data:: DN_P_NOSPACEAFTERRDN
|
|
|
|
.. py:data:: DN_PEDANTIC
|
|
|
|
|
|
|
|
.. _ldap-exceptions:
|
|
|
|
Exceptions
|
|
==========
|
|
|
|
The module defines the following exceptions:
|
|
|
|
.. py:exception:: LDAPError
|
|
|
|
This is the base class of all execeptions raised by the module :py:mod:`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 :py:const:`desc`
|
|
(giving an English description of the error class)
|
|
and/or a string value for the key :py:const:`info`
|
|
(giving a string containing more information that the server may have sent).
|
|
|
|
A third possible field of this dictionary is :py:const:`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.
|
|
|
|
|
|
.. py:exception:: ADMINLIMIT_EXCEEDED
|
|
|
|
.. py:exception:: AFFECTS_MULTIPLE_DSAS
|
|
|
|
.. py:exception:: ALIAS_DEREF_PROBLEM
|
|
|
|
A problem was encountered when dereferencing an alias.
|
|
(Sets the :py:const:`matched` field.)
|
|
|
|
.. py:exception:: ALIAS_PROBLEM
|
|
|
|
An alias in the directory points to a nonexistent entry.
|
|
(Sets the :py:const:`matched` field.)
|
|
|
|
.. py:exception:: ALREADY_EXISTS
|
|
|
|
The entry already exists. E.g. the *dn* specified with :py:meth:`add()`
|
|
already exists in the DIT.
|
|
|
|
.. py:exception:: AUTH_UNKNOWN
|
|
|
|
The authentication method specified to :py:meth:`bind()` is not known.
|
|
|
|
.. py:exception:: BUSY
|
|
|
|
The DSA is busy.
|
|
|
|
.. py:exception:: CLIENT_LOOP
|
|
|
|
.. py:exception:: COMPARE_FALSE
|
|
|
|
A compare operation returned false.
|
|
(This exception should never be seen because :py:meth:`compare()` returns
|
|
a boolean result.)
|
|
|
|
.. py:exception:: COMPARE_TRUE
|
|
|
|
A compare operation returned true.
|
|
(This exception should never be seen because :py:meth:`compare()` returns
|
|
a boolean result.)
|
|
|
|
.. py:exception:: CONFIDENTIALITY_REQUIRED
|
|
|
|
Indicates that the session is not protected by a protocol such
|
|
as Transport Layer Security (TLS), which provides session
|
|
confidentiality.
|
|
|
|
.. py:exception:: CONNECT_ERROR
|
|
|
|
.. py:exception:: 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).
|
|
|
|
.. py:exception:: CONTROL_NOT_FOUND
|
|
|
|
.. py:exception:: DECODING_ERROR
|
|
|
|
An error was encountered decoding a result from the LDAP server.
|
|
|
|
.. py:exception:: ENCODING_ERROR
|
|
|
|
An error was encountered encoding parameters to send to the LDAP server.
|
|
|
|
.. py:exception:: FILTER_ERROR
|
|
|
|
An invalid filter was supplied to :py:meth:`search()`
|
|
(e.g. unbalanced parentheses).
|
|
|
|
.. py:exception:: INAPPROPRIATE_AUTH
|
|
|
|
Inappropriate authentication was specified (e.g. :py:const:`AUTH_SIMPLE`
|
|
was specified and the entry does not have a userPassword attribute).
|
|
|
|
.. py:exception:: INAPPROPRIATE_MATCHING
|
|
|
|
Filter type not supported for the specified attribute.
|
|
|
|
.. py:exception:: INSUFFICIENT_ACCESS
|
|
|
|
The user has insufficient access to perform the operation.
|
|
|
|
.. py:exception:: INVALID_CREDENTIALS
|
|
|
|
Invalid credentials were presented during :py:meth:`bind()` or
|
|
:py:meth:`simple_bind()`.
|
|
(e.g., the wrong password).
|
|
|
|
.. py:exception:: INVALID_DN_SYNTAX
|
|
|
|
A syntactically invalid DN was specified. (Sets the :py:const:`matched` field.)
|
|
|
|
.. py:exception:: INVALID_SYNTAX
|
|
|
|
An attribute value specified by the client did not comply to the
|
|
syntax defined in the server-side schema.
|
|
|
|
.. py:exception:: IS_LEAF
|
|
|
|
The object specified is a leaf of the diretcory tree.
|
|
Sets the :py:const:`matched` field of the exception dictionary value.
|
|
|
|
.. py:exception:: LOCAL_ERROR
|
|
|
|
Some local error occurred. This is usually due to failed memory allocation.
|
|
|
|
.. py:exception:: LOOP_DETECT
|
|
|
|
A loop was detected.
|
|
|
|
.. py:exception:: MORE_RESULTS_TO_RETURN
|
|
|
|
.. py:exception:: NAMING_VIOLATION
|
|
|
|
A naming violation occurred. This is raised e.g. if the LDAP server
|
|
has constraints about the tree naming.
|
|
|
|
.. py:exception:: NO_OBJECT_CLASS_MODS
|
|
|
|
Modifying the objectClass attribute as requested is not allowed
|
|
(e.g. modifying structural object class of existing entry).
|
|
|
|
.. py:exception:: NOT_ALLOWED_ON_NONLEAF
|
|
|
|
The operation is not allowed on a non-leaf object.
|
|
|
|
.. py:exception:: NOT_ALLOWED_ON_RDN
|
|
|
|
The operation is not allowed on an RDN.
|
|
|
|
.. py:exception:: NOT_SUPPORTED
|
|
|
|
.. py:exception:: NO_MEMORY
|
|
|
|
.. py:exception:: NO_OBJECT_CLASS_MODS
|
|
|
|
Object class modifications are not allowed.
|
|
|
|
.. py:exception:: NO_RESULTS_RETURNED
|
|
|
|
.. py:exception:: NO_SUCH_ATTRIBUTE
|
|
|
|
The attribute type specified does not exist in the entry.
|
|
|
|
.. py:exception:: NO_SUCH_OBJECT
|
|
|
|
The specified object does not exist in the directory.
|
|
Sets the :py:const:`matched` field of the exception dictionary value.
|
|
|
|
.. py:exception:: 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).
|
|
|
|
.. py:exception:: OPERATIONS_ERROR
|
|
|
|
An operations error occurred.
|
|
|
|
.. py:exception:: OTHER
|
|
|
|
An unclassified error occurred.
|
|
|
|
.. py:exception:: PARAM_ERROR
|
|
|
|
An ldap routine was called with a bad parameter.
|
|
|
|
.. py:exception:: 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.)
|
|
|
|
.. py:exception:: PROTOCOL_ERROR
|
|
|
|
A violation of the LDAP protocol was detected.
|
|
|
|
.. py:exception:: 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.
|
|
|
|
.. py:exception:: SASL_BIND_IN_PROGRESS
|
|
|
|
.. py:exception:: SERVER_DOWN
|
|
|
|
The LDAP library can't contact the LDAP server.
|
|
|
|
.. py:exception:: SIZELIMIT_EXCEEDED
|
|
|
|
An LDAP size limit was exceeded.
|
|
This could be due to a ``sizelimit`` configuration on the LDAP server.
|
|
|
|
.. py:exception:: STRONG_AUTH_NOT_SUPPORTED
|
|
|
|
The LDAP server does not support strong authentication.
|
|
|
|
.. py:exception:: STRONG_AUTH_REQUIRED
|
|
|
|
Strong authentication is required for the operation.
|
|
|
|
.. py:exception:: TIMELIMIT_EXCEEDED
|
|
|
|
An LDAP time limit was exceeded.
|
|
|
|
.. py:exception:: TIMEOUT
|
|
|
|
A timelimit was exceeded while waiting for a result from the server.
|
|
|
|
.. py:exception:: TYPE_OR_VALUE_EXISTS
|
|
|
|
An attribute type or attribute value specified already
|
|
exists in the entry.
|
|
|
|
.. py:exception:: UNAVAILABLE
|
|
|
|
The DSA is unavailable.
|
|
|
|
.. py:exception:: 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.
|
|
|
|
.. py:exception:: UNDEFINED_TYPE
|
|
|
|
An attribute type used is not defined in the server-side schema.
|
|
|
|
.. py:exception:: UNWILLING_TO_PERFORM
|
|
|
|
The DSA is unwilling to perform the operation.
|
|
|
|
.. py:exception:: USER_CANCELLED
|
|
|
|
The operation was cancelled via the :py:meth:`abandon()` method.
|
|
|
|
The above exceptions are raised when a result code from an underlying API
|
|
call does not indicate success.
|
|
|
|
|
|
.. _ldap-objects:
|
|
|
|
LDAPObject classes
|
|
==================
|
|
|
|
.. py:class:: LDAPObject
|
|
|
|
Instances of :py:class:`LDAPObject` are returned by :py:func:`initialize()`
|
|
and :py:func:`open()` (deprecated). The connection is automatically unbound
|
|
and closed when the LDAP object is deleted. Internally :py:class:`LDAPObject`
|
|
is set to :py:class:`SimpleLDAPObject` by default.
|
|
|
|
|
|
.. py:class:: SimpleLDAPObject(uri [, trace_level=0 [, trace_file=sys.stdout [, trace_stack_limit=5]]])
|
|
|
|
Instances of :py:class:`LDAPObject` are returned by :py:func:`initialize()`
|
|
and :py:func:`open()` (deprecated). The connection is automatically unbound
|
|
and closed when the LDAP object is deleted.
|
|
|
|
|
|
.. py:class:: 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 :py:class:`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 :py:exc:`ldap.SERVER_DOWN` exception.
|
|
|
|
*retry_delay* specifies the time in seconds between reconnect attempts.
|
|
|
|
|
|
Arguments for LDAPv3 controls
|
|
-----------------------------
|
|
|
|
The :py:mod:`ldap.controls` module can be used for constructing and
|
|
decoding LDAPv3 controls. These arguments are available in the methods
|
|
with names ending in :py:const:`_ext` or :py:const:`_ext_s`:
|
|
|
|
*serverctrls*
|
|
is a list of :py:class:`ldap.controls.LDAPControl` instances sent to the server along
|
|
with the LDAP request (see module :py:mod:`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 :py:class:`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 :py:meth:`result()`.
|
|
|
|
Methods with names ending in :py:const:`_s` are the synchronous form
|
|
and wait for and return with the server's result, or with
|
|
:py:const:`None` if no data is expected.
|
|
|
|
|
|
:class:`LDAPObject` instances have the following methods:
|
|
|
|
.. py:method:: LDAPObject.abandon(msgid) -> None
|
|
|
|
.. py:method:: 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 :py:meth:`search()`, :py:meth:`modify()`, etc.
|
|
The caller can expect that the result of an abandoned operation will not be
|
|
returned from a future call to :py:meth:`result()`.
|
|
|
|
*serverctrls* and *clientctrls* like described above.
|
|
|
|
|
|
.. py:method:: LDAPObject.add(dn, modlist) -> int
|
|
|
|
.. py:method:: LDAPObject.add_s(dn, modlist) -> None
|
|
|
|
.. py:method:: LDAPObject.add_ext(dn, modlist [, serverctrls=None [, clientctrls=None]]) -> int
|
|
|
|
.. py:method:: 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 :py:meth:`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 :py:meth:`add()` and :py:meth:`add_ext()`
|
|
return the message ID of the initiated request.
|
|
|
|
*serverctrls* and *clientctrls* like described above.
|
|
|
|
.. py:method:: LDAPObject.bind(who, cred, method) -> int
|
|
|
|
.. py:method:: LDAPObject.bind_s(who, cred, method) -> None
|
|
|
|
.. py:method:: LDAPObject.simple_bind([who='' [, cred='' [, serverctrls=None [, clientctrls=None]]]]) -> int
|
|
|
|
.. py:method:: LDAPObject.simple_bind_s([who='' [, cred='' [, serverctrls=None [, clientctrls=None]]]]) -> 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, :py:meth:`bind()`,
|
|
takes a third parameter, *method* which can currently solely
|
|
be :py:const:`AUTH_SIMPLE`.
|
|
|
|
|
|
.. py:method:: LDAPObject.sasl_interactive_bind_s(who, auth) -> None
|
|
|
|
This call is used to bind to the directory with a SASL bind request.
|
|
|
|
|
|
.. py:method:: 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 :py:meth:`result()`.
|
|
In opposite to :py:meth:`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
|
|
|
|
|
|
.. py:method:: LDAPObject.compare(dn, attr, value) -> int
|
|
|
|
.. py:method:: LDAPObject.compare_s(dn, attr, value) -> tuple
|
|
|
|
.. py:method:: LDAPObject.compare_ext(dn, attr, value [, serverctrls=None [, clientctrls=None]]) -> int
|
|
|
|
.. py:method:: 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 :py:const:`0` for false, or :py:const:`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
|
|
:py:meth:`result()`.
|
|
|
|
Note that the asynchronous technique yields the answer
|
|
by raising the exception objects :py:exc:`ldap.COMPARE_TRUE` or
|
|
:py:exc:`ldap.COMPARE_FALSE`.
|
|
|
|
*serverctrls* and *clientctrls* like described above.
|
|
|
|
.. note::
|
|
|
|
A design fault in the LDAP API prevents *value*
|
|
from containing *NULL* characters.
|
|
|
|
|
|
.. py:method:: LDAPObject.delete(dn) -> int
|
|
|
|
.. py:method:: LDAPObject.delete_s(dn) -> None
|
|
|
|
.. py:method:: LDAPObject.delete_ext(dn [, serverctrls=None [, clientctrls=None]]) -> int
|
|
|
|
.. py:method:: 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 :py:meth:`result()`.
|
|
|
|
*serverctrls* and *clientctrls* like described above.
|
|
|
|
|
|
.. py:method:: extop(extreq[,serverctrls=None[,clientctrls=None]]]) -> int
|
|
|
|
.. py:method:: 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 :py:meth:`extop_result()`.
|
|
|
|
The *extreq* is an instance of class :py:class:`ldap.extop.ExtendedRequest`
|
|
containing the parameters for the extended operation request.
|
|
|
|
If argument *extop_resp_class* is set to a sub-class of
|
|
:py:class:`ldap.extop.ExtendedResponse` this class is used to return an
|
|
object of this class instead of a raw BER value in respvalue.
|
|
|
|
.. py:method:: extop_result(self,msgid=ldap.RES_ANY,all=1,timeout=None) -> (respoid,respvalue)
|
|
|
|
Wrapper method around :py:meth:`result4()` just for retrieving
|
|
the result of an extended operation sent before.
|
|
|
|
|
|
.. py:method:: LDAPObject.modify(dn, modlist) -> int
|
|
|
|
.. py:method:: LDAPObject.modify_s(dn, modlist) -> None
|
|
|
|
.. py:method:: LDAPObject.modify_ext(dn, modlist [, serverctrls=None [, clientctrls=None]]) -> int
|
|
|
|
.. py:method:: 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 :py:const:`ldap.MOD_ADD`,
|
|
:py:const:`ldap.MOD_DELETE`, or :py:const:`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 :py:const:`None` indicating that all attributes are to be deleted.
|
|
|
|
*serverctrls* and *clientctrls* like described above.
|
|
|
|
The asynchronous methods :py:meth:`modify()` and :py:meth:`modify_ext()`
|
|
return the message ID of the initiated request.
|
|
|
|
You might want to look into sub-module :py:mod:`ldap.modlist` for
|
|
generating *modlist*.
|
|
|
|
|
|
.. py:method:: LDAPObject.modrdn(dn, newrdn [, delold=1]) -> int
|
|
|
|
|
|
.. py:method:: 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 :py:meth:`rename()` and :py:meth:`rename_s()` methods
|
|
since the modrdn2* routines in the C library are deprecated.
|
|
|
|
|
|
.. py:method:: LDAPObject.passwd(user, oldpw, newpw [, serverctrls=None [, clientctrls=None]]) -> int
|
|
|
|
.. py:method:: 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 :py:const:`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.
|
|
|
|
.. seealso::
|
|
|
|
:rfc:`3062` - LDAP Password Modify Extended Operation
|
|
|
|
|
|
|
|
.. py:method:: LDAPObject.rename(dn, newrdn [, newsuperior=None [, delold=1 [, serverctrls=None [, clientctrls=None]]]]) -> int
|
|
|
|
.. py:method:: 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.
|
|
|
|
.. py:method:: 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 :py:meth:`search()`, :py:meth:`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 :py:meth:`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 :py:const:`RES_ANY`
|
|
and the method :py:meth:`result2()` should be used instead.
|
|
|
|
The *all* parameter only has meaning for :py:meth:`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 :py:meth:`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
|
|
:py:const:`RES_SEARCH_ENTRY` and :py:const:`RES_SEARCH_REFERENCE`,
|
|
until the final result which has a result type of :py:const:`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 :py:const:`0` effects a poll.
|
|
If a timeout does occur, a :py:exc:`ldap.TIMEOUT` exception is raised,
|
|
unless polling, in which case ``(None, None)`` is returned.
|
|
|
|
The :py:meth:`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:
|
|
:py:const:`RES_BIND`, :py:const:`RES_SEARCH_ENTRY`,
|
|
:py:const:`RES_SEARCH_REFERENCE`, :py:const:`RES_SEARCH_RESULT`,
|
|
:py:const:`RES_MODIFY`, :py:const:`RES_ADD`, :py:const:`RES_DELETE`,
|
|
:py:const:`RES_MODRDN`, or :py:const:`RES_COMPARE`.
|
|
|
|
If *all* is :py:const:`0`, one response at a time is returned on
|
|
each call to :py:meth:`result()`, with termination indicated by
|
|
``result-data`` being an empty list.
|
|
|
|
See :py:meth:`search()` for a description of the search result's
|
|
``result-data``, otherwise the ``result-data`` is normally meaningless.
|
|
|
|
|
|
|
|
.. py:method:: LDAPObject.result2([msgid=RES_ANY [, all=1 [, timeout=None]]]) -> 3-tuple
|
|
|
|
This method behaves almost exactly like :py:meth:`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=``:py:const:`RES_ANY` to several consumer
|
|
threads which invoked a particular LDAP operation.
|
|
|
|
|
|
.. py:method:: LDAPObject.result3([msgid=RES_ANY [, all=1 [, timeout=None]]]) -> 4-tuple
|
|
|
|
This method behaves almost exactly like :py:meth:`result2()`. But it
|
|
returns an extra item in the tuple, the decoded server controls.
|
|
|
|
.. py:method:: 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 :py:meth:`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 :py:meth:`extop_result()` or
|
|
:py:meth:`extop_s()` instead.
|
|
|
|
*resp_ctrl_classes* is a dictionary mapping the OID of a response controls to a
|
|
:py:class:`ldap.controls.ResponseControl` class of response controls known by the
|
|
application. So the response control value will be automatically decoded.
|
|
If :py:const:`None` the global dictionary :py:data:`ldap.controls.KNOWN_RESPONSE_CONTROLS`
|
|
is used instead.
|
|
|
|
.. py:method:: LDAPObject.search(base, scope [,filterstr='(objectClass=*)' [, attrlist=None [, attrsonly=0]]]) ->int
|
|
|
|
.. py:method:: LDAPObject.search_s(base, scope [,filterstr='(objectClass=*)' [, attrlist=None [, attrsonly=0]]]) ->list|None
|
|
|
|
.. py:method:: LDAPObject.search_st(base, scope [,filterstr='(objectClass=*)' [, attrlist=None [, attrsonly=0 [, timeout=-1]]]]) -> list|None
|
|
|
|
.. py:method:: LDAPObject.search_ext(base, scope [,filterstr='(objectClass=*)' [, attrlist=None [, attrsonly=0 [, serverctrls=None [, clientctrls=None [, timeout=-1 [, sizelimit=0]]]]]]]) -> int
|
|
|
|
.. py:method:: 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
|
|
:py:const:`SCOPE_BASE` (to search the object itself),
|
|
:py:const:`SCOPE_ONELEVEL` (to search the object's immediate children), or
|
|
:py:const:`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.
|
|
|
|
.. seealso::
|
|
|
|
: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 :cfunc:`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 :py:const:`None`, all the attributes of each entry are returned.
|
|
|
|
*serverctrls* and *clientctrls* like described above.
|
|
|
|
The synchronous form with timeout, :py:meth:`search_st()` or :py:meth:`search_ext_s()`,
|
|
will block for at most *timeout* seconds (or indefinitely if *timeout*
|
|
is negative). A :py:exc:`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 :py:meth:`search_ext()`
|
|
or :py:meth:`search_ext_s()` (client-side search limit). If non-zero
|
|
not more than *sizelimit* results are returned by the server.
|
|
|
|
|
|
|
|
.. py:method:: LDAPObject.start_tls_s() -> None
|
|
|
|
Negotiate TLS with server. The ``version`` attribute must have been
|
|
set to :py:const:`VERSION3` (which it is by default) before calling this method.
|
|
If TLS could not be started an exception will be raised.
|
|
|
|
.. seealso::
|
|
|
|
:rfc:`2830` - Lightweight Directory Access Protocol (v3): Extension for Transport Layer Security
|
|
|
|
|
|
|
|
.. py:method:: LDAPObject.unbind() -> int
|
|
|
|
.. py:method:: LDAPObject.unbind_s() -> None
|
|
|
|
.. py:method:: LDAPObject.unbind_ext([, serverctrls=None [, clientctrls=None]]) -> int
|
|
|
|
.. py:method:: 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.
|
|
|
|
|
|
.. py:method:: 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.
|
|
|
|
.. seealso::
|
|
|
|
:rfc:`4532` - Lightweight Directory Access Protocol (LDAP) "Who am I?" Operation
|
|
|
|
|
|
Connection-specific LDAP options
|
|
--------------------------------
|
|
|
|
.. py:method:: LDAPObject.get_option(option) -> int|string
|
|
|
|
This method returns the value of the LDAPObject option
|
|
specified by *option*.
|
|
|
|
|
|
.. py:method:: 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.
|
|
|
|
.. py:attribute:: LDAPObject.deref -> int
|
|
|
|
Controls whether aliases are automatically dereferenced.
|
|
This must be one of :py:const:`DEREF_NEVER`, :py:const:`DEREF_SEARCHING`,
|
|
:py:const:`DEREF_FINDING` or :py:const:`DEREF_ALWAYS`.
|
|
This option is mapped to option constant :py:const:`OPT_DEREF`
|
|
and used in the underlying OpenLDAP client lib.
|
|
|
|
|
|
.. py:attribute:: LDAPObject.network_timeout -> int
|
|
|
|
Limit on waiting for a network response, in seconds.
|
|
Defaults to :py:const:`NO_LIMIT`.
|
|
This option is mapped to option constant :py:const:`OPT_NETWORK_TIMEOUT`
|
|
and used in the underlying OpenLDAP client lib.
|
|
|
|
|
|
.. py:attribute:: LDAPObject.protocol_version -> int
|
|
|
|
Version of LDAP in use (either :py:const:`VERSION2` for LDAPv2
|
|
or :py:const:`VERSION3` for LDAPv3).
|
|
This option is mapped to option constant :py:const:`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 :py:func:`ldap.initialize()` and before submitting
|
|
the first request.
|
|
|
|
|
|
.. py:attribute:: LDAPObject.sizelimit -> int
|
|
|
|
Limit on size of message to receive from server.
|
|
Defaults to :py:const:`NO_LIMIT`.
|
|
This option is mapped to option constant :py:const:`OPT_SIZELIMIT`
|
|
and used in the underlying OpenLDAP client lib. Its use is deprecated
|
|
in favour of *sizelimit* parameter when using :py:meth:`search_ext()`.
|
|
|
|
|
|
.. py:attribute:: LDAPObject.timelimit -> int
|
|
|
|
Limit on waiting for any response, in seconds.
|
|
Defaults to :py:const:`NO_LIMIT`.
|
|
This option is mapped to option constant :py:const:`OPT_TIMELIMIT`
|
|
and used in the underlying OpenLDAP client lib. Its use is deprecated
|
|
in favour of using :py:attr:`timeout`.
|
|
|
|
|
|
.. py:attribute:: LDAPObject.timeout -> int
|
|
|
|
Limit on waiting for any response, in seconds.
|
|
Defaults to :py:const:`NO_LIMIT`.
|
|
This option is used in the wrapper module.
|
|
|
|
|
|
.. _ldap-example:
|
|
|
|
Example
|
|
=======
|
|
|
|
The following example demonstrates how to open a connection to an
|
|
LDAP server using the :py:mod:`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)
|
|
|