ldap.rst 37 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125
  1. .. % $Id: ldap.rst,v 1.26 2011/09/14 18:21:06 stroeder Exp $
  2. ********************************************
  3. :py:mod:`ldap` LDAP library interface module
  4. ********************************************
  5. .. py:module:: ldap
  6. :platform: Posix, Windows
  7. :synopsis: Access to an underlying LDAP C library.
  8. .. moduleauthor:: python-ldap project (see http://www.python-ldap.org/)
  9. This module provides access to the LDAP (Lightweight Directory Access Protocol)
  10. C API implemented in OpenLDAP 2.3 or newer. It is similar to the C API, with
  11. the notable differences that lists are manipulated via Python list operations
  12. and errors appear as exceptions. For far more detailed information on the C
  13. interface, please see the (expired) draft-ietf-ldapext-ldap-c-api-04. This
  14. documentation is current for the Python LDAP module, version |release|. Source
  15. and binaries are available from http://www.python-ldap.org/.
  16. Functions
  17. =========
  18. This module defines the following functions:
  19. .. py:function:: initialize(uri [, trace_level=0 [, trace_file=sys.stdout [, trace_stack_limit=None]]]) -> LDAPObject object
  20. Initializes a new connection object for accessing the given LDAP server,
  21. and return an LDAP object (see :ref:`ldap-objects`) used to perform operations
  22. on that server. Parameter *uri* has to be a valid LDAP URL.
  23. Note that the C wrapper function :py:func:_ldap.initialize() is called which calls
  24. the OpenLDAP funtion ldap_initialize(). Calling this function just initializes
  25. the LDAP connection struct in the C API - nothing else. The first call to
  26. an operation method (bind, search etc.) then really opens the connection.
  27. Before that nothing is sent on the wire.
  28. The optional arguments are for generating debug log information:
  29. *trace_level* specifies the amount of information being logged,
  30. *trace_file* specifies a file-like object as target of the debug log and
  31. *trace_stack_limit* specifies the stack limit of tracebacks in debug log.
  32. Possible values for *trace_level* are
  33. :py:const:`0` for no logging,
  34. :py:const:`1` for only logging the method calls with arguments,
  35. :py:const:`2` for logging the method calls with arguments and the complete results and
  36. :py:const:`9` for also logging the traceback of method calls.
  37. .. seealso::
  38. :rfc:`4516` - Lightweight Directory Access Protocol (LDAP): Uniform Resource Locator
  39. .. py:function:: open(host [, port=PORT]) -> LDAPObject object
  40. Opens a new connection with an LDAP server, and return an LDAP object (see
  41. :ref:`ldap-objects`) used to perform operations on that server. *host* is a
  42. string containing solely the host name. *port* is an integer specifying the
  43. port where the LDAP server is listening (default is 389).
  44. Note: Using this function is deprecated.
  45. .. py:function:: get_option(option) -> int|string
  46. This function returns the value of the global option specified by *option*.
  47. .. py:function:: set_option(option, invalue) -> None
  48. This function sets the value of the global option specified by *option* to
  49. *invalue*.
  50. .. _ldap-constants:
  51. Constants
  52. =========
  53. The module defines various constants. Note that some constants depend
  54. on the build options and which underlying libs were used or even on
  55. the version of the libs. So before using those constants the application has
  56. to explicitly check whether they are available.
  57. General
  58. -------
  59. .. py:data:: PORT
  60. The assigned TCP port number (389) that LDAP servers listen on.
  61. .. py:data:: SASL_AVAIL
  62. Integer where a non-zero value indicates that python-ldap was built with
  63. support for SASL (Cyrus-SASL).
  64. .. py:data:: TLS_AVAIL
  65. Integer where a non-zero value indicates that python-ldap was built with
  66. support for SSL/TLS (OpenSSL or similar libs).
  67. .. _ldap-options:
  68. Options
  69. -------
  70. .. seealso::
  71. :manpage:`ldap.conf{5}` and :manpage:`ldap_get_options{3}`
  72. For use with functions :py:func:set_option() and :py:func:get_option()
  73. and methods :py:method:LDAPObject.set_option() and :py:method:LDAPObject.get_option() the
  74. following option identifiers are defined as constants:
  75. .. py:data:: OPT_API_FEATURE_INFO
  76. .. py:data:: OPT_API_INFO
  77. .. py:data:: OPT_CLIENT_CONTROLS
  78. .. py:data:: OPT_DEBUG_LEVEL
  79. Sets the debug level within the underlying LDAP C lib.
  80. .. py:data:: OPT_DEFBASE
  81. .. py:data:: OPT_DEREF
  82. Specifies how alias derefencing is done within the underlying LDAP C lib.
  83. .. py:data:: OPT_ERROR_STRING
  84. .. py:data:: OPT_DIAGNOSTIC_MESSAGE
  85. .. py:data:: OPT_HOST_NAME
  86. .. py:data:: OPT_MATCHED_DN
  87. .. py:data:: OPT_NETWORK_TIMEOUT
  88. .. py:data:: OPT_PROTOCOL_VERSION
  89. Sets the LDAP protocol version used for a connection. This is mapped to
  90. object attribute `ldap.LDAPObject.protocol_version`
  91. .. py:data:: OPT_REFERRALS
  92. int specifying whether referrals should be automatically chased within
  93. the underlying LDAP C lib.
  94. .. py:data:: OPT_REFHOPLIMIT
  95. .. py:data:: OPT_RESTART
  96. .. py:data:: OPT_SERVER_CONTROLS
  97. .. py:data:: OPT_SIZELIMIT
  98. .. py:data:: OPT_SUCCESS
  99. .. py:data:: OPT_TIMELIMIT
  100. .. py:data:: OPT_TIMEOUT
  101. .. py:data:: OPT_URI
  102. .. _ldap-sasl-options:
  103. SASL options
  104. ::::::::::::
  105. .. py:data:: OPT_X_SASL_AUTHCID
  106. .. py:data:: OPT_X_SASL_AUTHZID
  107. .. py:data:: OPT_X_SASL_MECH
  108. .. py:data:: OPT_X_SASL_NOCANON
  109. If set to zero SASL host name canonicalization is disabled.
  110. .. py:data:: OPT_X_SASL_REALM
  111. .. py:data:: OPT_X_SASL_SECPROPS
  112. .. py:data:: OPT_X_SASL_SSF
  113. .. py:data:: OPT_X_SASL_SSF_EXTERNAL
  114. .. py:data:: OPT_X_SASL_SSF_MAX
  115. .. py:data:: OPT_X_SASL_SSF_MIN
  116. .. _ldap-tls-options:
  117. TLS options
  118. :::::::::::
  119. .. py:data:: OPT_X_TLS
  120. .. py:data:: OPT_X_TLS_ALLOW
  121. .. py:data:: OPT_X_TLS_CACERTDIR
  122. .. py:data:: OPT_X_TLS_CACERTFILE
  123. .. py:data:: OPT_X_TLS_CERTFILE
  124. .. py:data:: OPT_X_TLS_CIPHER_SUITE
  125. .. py:data:: OPT_X_TLS_CTX
  126. .. py:data:: OPT_X_TLS_DEMAND
  127. .. py:data:: OPT_X_TLS_HARD
  128. .. py:data:: OPT_X_TLS_KEYFILE
  129. .. py:data:: OPT_X_TLS_NEVER
  130. .. py:data:: OPT_X_TLS_RANDOM_FILE
  131. .. py:data:: OPT_X_TLS_REQUIRE_CERT
  132. .. py:data:: OPT_X_TLS_TRY
  133. .. _ldap-keepalive-options:
  134. Keepalive options
  135. :::::::::::::::::
  136. .. py:data:: OPT_X_KEEPALIVE_IDLE
  137. .. py:data:: OPT_X_KEEPALIVE_PROBES
  138. .. py:data:: OPT_X_KEEPALIVE_INTERVAL
  139. .. _ldap-dn-flags:
  140. DN format flags
  141. ----------------
  142. This constants are used for DN-parsing functions found in
  143. sub-module :py:mod:`ldap.dn`.
  144. .. seealso::
  145. :manpage:`ldap_str2dn{3}`
  146. .. py:data:: DN_FORMAT_LDAP
  147. .. py:data:: DN_FORMAT_LDAPV3
  148. .. py:data:: DN_FORMAT_LDAPV2
  149. .. py:data:: DN_FORMAT_DCE
  150. .. py:data:: DN_FORMAT_UFN
  151. .. py:data:: DN_FORMAT_AD_CANONICAL
  152. .. py:data:: DN_FORMAT_MASK
  153. .. py:data:: DN_PRETTY
  154. .. py:data:: DN_SKIP
  155. .. py:data:: DN_P_NOLEADTRAILSPACES
  156. .. py:data:: DN_P_NOSPACEAFTERRDN
  157. .. py:data:: DN_PEDANTIC
  158. .. _ldap-exceptions:
  159. Exceptions
  160. ==========
  161. The module defines the following exceptions:
  162. .. py:exception:: LDAPError
  163. This is the base class of all execeptions raised by the module :py:mod:`ldap`.
  164. Unlike the C interface, errors are not returned as result codes, but
  165. are instead turned into exceptions, raised as soon an the error condition
  166. is detected.
  167. The exceptions are accompanied by a dictionary possibly
  168. containing an string value for the key :py:const:`desc`
  169. (giving an English description of the error class)
  170. and/or a string value for the key :py:const:`info`
  171. (giving a string containing more information that the server may have sent).
  172. A third possible field of this dictionary is :py:const:`matched` and
  173. is set to a truncated form of the name provided or alias dereferenced
  174. for the lowest entry (object or alias) that was matched.
  175. .. py:exception:: ADMINLIMIT_EXCEEDED
  176. .. py:exception:: AFFECTS_MULTIPLE_DSAS
  177. .. py:exception:: ALIAS_DEREF_PROBLEM
  178. A problem was encountered when dereferencing an alias.
  179. (Sets the :py:const:`matched` field.)
  180. .. py:exception:: ALIAS_PROBLEM
  181. An alias in the directory points to a nonexistent entry.
  182. (Sets the :py:const:`matched` field.)
  183. .. py:exception:: ALREADY_EXISTS
  184. The entry already exists. E.g. the *dn* specified with :py:meth:`add()`
  185. already exists in the DIT.
  186. .. py:exception:: AUTH_UNKNOWN
  187. The authentication method specified to :py:meth:`bind()` is not known.
  188. .. py:exception:: BUSY
  189. The DSA is busy.
  190. .. py:exception:: CLIENT_LOOP
  191. .. py:exception:: COMPARE_FALSE
  192. A compare operation returned false.
  193. (This exception should never be seen because :py:meth:`compare()` returns
  194. a boolean result.)
  195. .. py:exception:: COMPARE_TRUE
  196. A compare operation returned true.
  197. (This exception should never be seen because :py:meth:`compare()` returns
  198. a boolean result.)
  199. .. py:exception:: CONFIDENTIALITY_REQUIRED
  200. Indicates that the session is not protected by a protocol such
  201. as Transport Layer Security (TLS), which provides session
  202. confidentiality.
  203. .. py:exception:: CONNECT_ERROR
  204. .. py:exception:: CONSTRAINT_VIOLATION
  205. An attribute value specified or an operation started violates some
  206. server-side constraint
  207. (e.g., a postalAddress has too many lines or a line that is too long
  208. or a password is expired).
  209. .. py:exception:: CONTROL_NOT_FOUND
  210. .. py:exception:: DECODING_ERROR
  211. An error was encountered decoding a result from the LDAP server.
  212. .. py:exception:: ENCODING_ERROR
  213. An error was encountered encoding parameters to send to the LDAP server.
  214. .. py:exception:: FILTER_ERROR
  215. An invalid filter was supplied to :py:meth:`search()`
  216. (e.g. unbalanced parentheses).
  217. .. py:exception:: INAPPROPRIATE_AUTH
  218. Inappropriate authentication was specified (e.g. :py:const:`AUTH_SIMPLE`
  219. was specified and the entry does not have a userPassword attribute).
  220. .. py:exception:: INAPPROPRIATE_MATCHING
  221. Filter type not supported for the specified attribute.
  222. .. py:exception:: INSUFFICIENT_ACCESS
  223. The user has insufficient access to perform the operation.
  224. .. py:exception:: INVALID_CREDENTIALS
  225. Invalid credentials were presented during :py:meth:`bind()` or
  226. :py:meth:`simple_bind()`.
  227. (e.g., the wrong password).
  228. .. py:exception:: INVALID_DN_SYNTAX
  229. A syntactically invalid DN was specified. (Sets the :py:const:`matched` field.)
  230. .. py:exception:: INVALID_SYNTAX
  231. An attribute value specified by the client did not comply to the
  232. syntax defined in the server-side schema.
  233. .. py:exception:: IS_LEAF
  234. The object specified is a leaf of the diretcory tree.
  235. Sets the :py:const:`matched` field of the exception dictionary value.
  236. .. py:exception:: LOCAL_ERROR
  237. Some local error occurred. This is usually due to failed memory allocation.
  238. .. py:exception:: LOOP_DETECT
  239. A loop was detected.
  240. .. py:exception:: MORE_RESULTS_TO_RETURN
  241. .. py:exception:: NAMING_VIOLATION
  242. A naming violation occurred. This is raised e.g. if the LDAP server
  243. has constraints about the tree naming.
  244. .. py:exception:: NO_OBJECT_CLASS_MODS
  245. Modifying the objectClass attribute as requested is not allowed
  246. (e.g. modifying structural object class of existing entry).
  247. .. py:exception:: NOT_ALLOWED_ON_NONLEAF
  248. The operation is not allowed on a non-leaf object.
  249. .. py:exception:: NOT_ALLOWED_ON_RDN
  250. The operation is not allowed on an RDN.
  251. .. py:exception:: NOT_SUPPORTED
  252. .. py:exception:: NO_MEMORY
  253. .. py:exception:: NO_OBJECT_CLASS_MODS
  254. Object class modifications are not allowed.
  255. .. py:exception:: NO_RESULTS_RETURNED
  256. .. py:exception:: NO_SUCH_ATTRIBUTE
  257. The attribute type specified does not exist in the entry.
  258. .. py:exception:: NO_SUCH_OBJECT
  259. The specified object does not exist in the directory.
  260. Sets the :py:const:`matched` field of the exception dictionary value.
  261. .. py:exception:: OBJECT_CLASS_VIOLATION
  262. An object class violation occurred when the LDAP server checked
  263. the data sent by the client against the server-side schema
  264. (e.g. a "must" attribute was missing in the entry data).
  265. .. py:exception:: OPERATIONS_ERROR
  266. An operations error occurred.
  267. .. py:exception:: OTHER
  268. An unclassified error occurred.
  269. .. py:exception:: PARAM_ERROR
  270. An ldap routine was called with a bad parameter.
  271. .. py:exception:: PARTIAL_RESULTS
  272. Partial results only returned. This exception is raised if
  273. a referral is received when using LDAPv2.
  274. (This exception should never be seen with LDAPv3.)
  275. .. py:exception:: PROTOCOL_ERROR
  276. A violation of the LDAP protocol was detected.
  277. .. py:exception:: RESULTS_TOO_LARGE
  278. The result does not fit into a UDP packet. This happens only when using
  279. UDP-based CLDAP (connection-less LDAP) which is not supported anyway.
  280. .. py:exception:: SASL_BIND_IN_PROGRESS
  281. .. py:exception:: SERVER_DOWN
  282. The LDAP library can't contact the LDAP server.
  283. .. py:exception:: SIZELIMIT_EXCEEDED
  284. An LDAP size limit was exceeded.
  285. This could be due to a ``sizelimit`` configuration on the LDAP server.
  286. .. py:exception:: STRONG_AUTH_NOT_SUPPORTED
  287. The LDAP server does not support strong authentication.
  288. .. py:exception:: STRONG_AUTH_REQUIRED
  289. Strong authentication is required for the operation.
  290. .. py:exception:: TIMELIMIT_EXCEEDED
  291. An LDAP time limit was exceeded.
  292. .. py:exception:: TIMEOUT
  293. A timelimit was exceeded while waiting for a result from the server.
  294. .. py:exception:: TYPE_OR_VALUE_EXISTS
  295. An attribute type or attribute value specified already
  296. exists in the entry.
  297. .. py:exception:: UNAVAILABLE
  298. The DSA is unavailable.
  299. .. py:exception:: UNAVAILABLE_CRITICAL_EXTENSION
  300. Indicates that the LDAP server was unable to satisfy a request
  301. because one or more critical extensions were not available. Either
  302. the server does not support the control or the control is not appropriate
  303. for the operation type.
  304. .. py:exception:: UNDEFINED_TYPE
  305. An attribute type used is not defined in the server-side schema.
  306. .. py:exception:: UNWILLING_TO_PERFORM
  307. The DSA is unwilling to perform the operation.
  308. .. py:exception:: USER_CANCELLED
  309. The operation was cancelled via the :py:meth:`abandon()` method.
  310. The above exceptions are raised when a result code from an underlying API
  311. call does not indicate success.
  312. .. _ldap-objects:
  313. LDAPObject classes
  314. ==================
  315. .. py:class:: LDAPObject
  316. Instances of :py:class:`LDAPObject` are returned by :py:func:`initialize()`
  317. and :py:func:`open()` (deprecated). The connection is automatically unbound
  318. and closed when the LDAP object is deleted. Internally :py:class:`LDAPObject`
  319. is set to :py:class:`SimpleLDAPObject` by default.
  320. .. py:class:: SimpleLDAPObject(uri [, trace_level=0 [, trace_file=sys.stdout [, trace_stack_limit=5]]])
  321. Instances of :py:class:`LDAPObject` are returned by :py:func:`initialize()`
  322. and :py:func:`open()` (deprecated). The connection is automatically unbound
  323. and closed when the LDAP object is deleted.
  324. .. py:class:: ReconnectLDAPObject(uri [, trace_level=0 [, trace_file=sys.stdout [, trace_stack_limit=5] [, retry_max=1 [, retry_delay=60.0]]]])
  325. This class is derived from :py:class:`SimpleLDAPObject` and used for automatic
  326. reconnects when using the synchronous request methods (see below). This class
  327. also implements the pickle protocol.
  328. For automatic reconnects it has additional arguments:
  329. *retry_max* specifies the number of reconnect attempts before
  330. re-raising the :py:exc:`ldap.SERVER_DOWN` exception.
  331. *retry_delay* specifies the time in seconds between reconnect attempts.
  332. Arguments for LDAPv3 controls
  333. -----------------------------
  334. The :py:mod:`ldap.controls` module can be used for constructing and
  335. decoding LDAPv3 controls. These arguments are available in the methods
  336. with names ending in :py:const:`_ext` or :py:const:`_ext_s`:
  337. *serverctrls*
  338. is a list of :py:class:`ldap.controls.LDAPControl` instances sent to the server along
  339. with the LDAP request (see module :py:mod:`ldap.controls`). These are
  340. controls which alter the behaviour of the server when processing the
  341. request if the control is supported by the server. The effect of controls
  342. might differ depending on the type of LDAP request or controls might not
  343. be applicable with certain LDAP requests at all.
  344. *clientctrls*
  345. is a list of :py:class:`ldap.controls.LDAPControl` instances passed to the
  346. client API and alter the behaviour of the client when processing the
  347. request.
  348. Sending LDAP requests
  349. ---------------------
  350. Most methods on LDAP objects initiate an asynchronous request to the
  351. LDAP server and return a message id that can be used later to retrieve
  352. the result with :py:meth:`result()`.
  353. Methods with names ending in :py:const:`_s` are the synchronous form
  354. and wait for and return with the server's result, or with
  355. :py:const:`None` if no data is expected.
  356. :class:`LDAPObject` instances have the following methods:
  357. .. py:method:: LDAPObject.abandon(msgid) -> None
  358. .. py:method:: LDAPObject.abandon_ext(msgid [, serverctrls=None [, clientctrls=None]]) -> None
  359. Abandons an LDAP operation in progress without waiting for a LDAP response.
  360. The *msgid* argument should be the message ID of an outstanding LDAP
  361. operation as returned by the asynchronous methods :py:meth:`search()`, :py:meth:`modify()`, etc.
  362. The caller can expect that the result of an abandoned operation will not be
  363. returned from a future call to :py:meth:`result()`.
  364. *serverctrls* and *clientctrls* like described above.
  365. .. py:method:: LDAPObject.add(dn, modlist) -> int
  366. .. py:method:: LDAPObject.add_s(dn, modlist) -> None
  367. .. py:method:: LDAPObject.add_ext(dn, modlist [, serverctrls=None [, clientctrls=None]]) -> int
  368. .. py:method:: LDAPObject.add_ext_s(dn, modlist [, serverctrls=None [, clientctrls=None]]) -> None
  369. Performs an LDAP add operation. The *dn* argument is the distinguished
  370. name (DN) of the entry to add, and *modlist* is a list of attributes to be
  371. added. The modlist is similar the one passed to :py:meth:`modify()`, except that the
  372. operation integer is omitted from the tuples in modlist. You might want to
  373. look into sub-module \refmodule{ldap.modlist} for generating the modlist.
  374. The asynchronous methods :py:meth:`add()` and :py:meth:`add_ext()`
  375. return the message ID of the initiated request.
  376. *serverctrls* and *clientctrls* like described above.
  377. .. py:method:: LDAPObject.bind(who, cred, method) -> int
  378. .. py:method:: LDAPObject.bind_s(who, cred, method) -> None
  379. .. py:method:: LDAPObject.simple_bind([who='' [, cred='']]) -> int
  380. .. py:method:: LDAPObject.simple_bind_s([who='' [, cred='']]) -> None
  381. After an LDAP object is created, and before any other operations can be
  382. attempted over the connection, a bind operation must be performed.
  383. This method attempts to bind with the LDAP server using
  384. either simple authentication, or Kerberos (if available).
  385. The first and most general method, :py:meth:`bind()`,
  386. takes a third parameter, *method* which can currently solely
  387. be :py:const:`AUTH_SIMPLE`.
  388. .. py:method:: LDAPObject.sasl_interactive_bind_s(who, auth) -> None
  389. This call is used to bind to the directory with a SASL bind request.
  390. .. py:method:: LDAPObject.cancel( cancelid, [, serverctrls=None [, clientctrls=None]]) -> None
  391. Send cancels extended operation for an LDAP operation specified by *cancelid*.
  392. The *cancelid* should be the message id of an outstanding LDAP operation as returned
  393. by the asynchronous methods search(), modify() etc. The caller
  394. can expect that the result of an abandoned operation will not be
  395. returned from a future call to :py:meth:`result()`.
  396. In opposite to :py:meth:`abandon()` this extended operation gets an result from
  397. the server and thus should be preferred if the server supports it.
  398. *serverctrls* and *clientctrls* like described above.
  399. :rfc:`3909` - Lightweight Directory Access Protocol (LDAP): Cancel Operation
  400. .. py:method:: LDAPObject.compare(dn, attr, value) -> int
  401. .. py:method:: LDAPObject.compare_s(dn, attr, value) -> tuple
  402. .. py:method:: LDAPObject.compare_ext(dn, attr, value [, serverctrls=None [, clientctrls=None]]) -> int
  403. .. py:method:: LDAPObject.compare_ext_s(dn, attr, value [, serverctrls=None [, clientctrls=None]]) -> tuple
  404. Perform an LDAP comparison between the attribute named *attr* of
  405. entry *dn*, and the value *value*. The synchronous forms
  406. returns :py:const:`0` for false, or :py:const:`1` for true.
  407. The asynchronous forms returns the message ID of the initiated request,
  408. and the result of the asynchronous compare can be obtained using
  409. :py:meth:`result()`.
  410. Note that the asynchronous technique yields the answer
  411. by raising the exception objects :py:exc:`ldap.COMPARE_TRUE` or
  412. :py:exc:`ldap.COMPARE_FALSE`.
  413. *serverctrls* and *clientctrls* like described above.
  414. .. note::
  415. A design fault in the LDAP API prevents *value*
  416. from containing *NULL* characters.
  417. .. py:method:: LDAPObject.delete(dn) -> int
  418. .. py:method:: LDAPObject.delete_s(dn) -> None
  419. .. py:method:: LDAPObject.delete_ext(dn [, serverctrls=None [, clientctrls=None]]) -> int
  420. .. py:method:: LDAPObject.delete_ext_s(dn [, serverctrls=None [, clientctrls=None]]) -> None
  421. Performs an LDAP delete operation on *dn*. The asynchronous form
  422. returns the message id of the initiated request, and the result can be obtained
  423. from a subsequent call to :py:meth:`result()`.
  424. *serverctrls* and *clientctrls* like described above.
  425. .. py:method:: extop(extreq[,serverctrls=None[,clientctrls=None]]]) -> int
  426. .. py:method:: extop_s(extreq[,serverctrls=None[,clientctrls=None[,extop_resp_class=None]]]]) -> (respoid,respvalue)
  427. Performs an LDAP extended operation. The asynchronous
  428. form returns the message id of the initiated request, and the
  429. result can be obtained from a subsequent call to :py:meth:`extop_result()`.
  430. The *extreq* is an instance of class :py:class:`ldap.extop.ExtendedRequest`
  431. containing the parameters for the extended operation request.
  432. If argument *extop_resp_class* is set to a sub-class of
  433. :py:class:`ldap.extop.ExtendedResponse` this class is used to return an
  434. object of this class instead of a raw BER value in respvalue.
  435. .. py:method:: extop_result(self,msgid=ldap.RES_ANY,all=1,timeout=None) -> (respoid,respvalue)
  436. Wrapper method around :py:meth:`result4()` just for retrieving
  437. the result of an extended operation sent before.
  438. .. py:method:: LDAPObject.modify(dn, modlist) -> int
  439. .. py:method:: LDAPObject.modify_s(dn, modlist) -> None
  440. .. py:method:: LDAPObject.modify_ext(dn, modlist [, serverctrls=None [, clientctrls=None]]) -> int
  441. .. py:method:: LDAPObject.modify_ext_s(dn, modlist [, serverctrls=None [, clientctrls=None]]) -> None
  442. Performs an LDAP modify operation on an entry's attributes.
  443. The *dn* argument is the distinguished name (DN) of the entry to modify,
  444. and *modlist* is a list of modifications to make to that entry.
  445. Each element in the list *modlist* should be a tuple of the form
  446. *(mod_op,mod_type,mod_vals)*,
  447. where *mod_op* indicates the operation (one of :py:const:`MOD_ADD`,
  448. :py:const:`MOD_DELETE`, or :py:const:`MOD_REPLACE`),
  449. *mod_type* is a string indicating the attribute type name, and
  450. *mod_vals* is either a string value or a list of string values to add,
  451. delete or replace respectively. For the delete operation, *mod_vals*
  452. may be :py:const:`None` indicating that all attributes are to be deleted.
  453. *serverctrls* and *clientctrls* like described above.
  454. The asynchronous methods :py:meth:`modify()` and :py:meth:`modify_ext()`
  455. return the message ID of the initiated request.
  456. You might want to look into sub-module :py:mod:`ldap.modlist` for
  457. generating *modlist*.
  458. .. py:method:: LDAPObject.modrdn(dn, newrdn [, delold=1]) -> int
  459. .. py:method:: LDAPObject.modrdn_s(dn, newrdn [, delold=1]) -> None
  460. Perform a ``modify RDN`` operation, (i.e. a renaming operation).
  461. These routines take *dn* (the DN of the entry whose RDN is to be changed,
  462. and *newrdn*, the new RDN to give to the entry. The optional parameter
  463. *delold* is used to specify whether the old RDN should be kept as an
  464. attribute of the entry or not.
  465. The asynchronous version returns the initiated message id.
  466. This operation is emulated by :py:meth:`rename()` and :py:meth:`rename_s()` methods
  467. since the modrdn2* routines in the C library are deprecated.
  468. .. py:method:: LDAPObject.passwd(user, oldpw, newpw [, serverctrls=None [, clientctrls=None]]) -> int
  469. .. py:method:: LDAPObject.passwd_s(user, oldpw, newpw [, serverctrls=None [, clientctrls=None]]) -> None
  470. Perform a ``LDAP Password Modify Extended Operation`` operation
  471. on the entry specified by *user*.
  472. The old password in *oldpw* is replaced with the new
  473. password in *newpw* by a LDAP server supporting this operation.
  474. If *oldpw* is not :py:const:`None` it has to match the old password
  475. of the specified *user* which is sometimes used when a user changes
  476. his own password.
  477. *serverctrls* and *clientctrls* like described above.
  478. The asynchronous version returns the initiated message id.
  479. .. seealso::
  480. :rfc:`3062` - LDAP Password Modify Extended Operation
  481. .. py:method:: LDAPObject.rename(dn, newrdn [, newsuperior=None [, delold=1 [, serverctrls=None [, clientctrls=None]]]]) -> int
  482. .. py:method:: LDAPObject.rename_s(dn, newrdn [, newsuperior=None [, delold=1 [, serverctrls=None [, clientctrls=None]]]]) -> None
  483. Perform a ``Rename`` operation, (i.e. a renaming operation).
  484. These routines take *dn* (the DN of the entry whose RDN is to be changed,
  485. and *newrdn*, the new RDN to give to the entry.
  486. The optional parameter *newsuperior* is used to specify
  487. a new parent DN for moving an entry in the tree
  488. (not all LDAP servers support this).
  489. The optional parameter *delold* is used to specify
  490. whether the old RDN should be kept as an attribute of the entry or not.
  491. *serverctrls* and *clientctrls* like described above.
  492. .. py:method:: LDAPObject.result([msgid=RES_ANY [, all=1 [, timeout=None]]]) -> 2-tuple
  493. This method is used to wait for and return the result of an operation
  494. previously initiated by one of the LDAP *asynchronous* operations
  495. (eg :py:meth:`search()`, :py:meth:`modify()`, etc.)
  496. The *msgid* parameter is the integer identifier returned by that method.
  497. The identifier is guaranteed to be unique across an LDAP session,
  498. and tells the :py:meth:`result()` method to request the result of that
  499. specific operation.
  500. If a result is desired from any one of the in-progress operations,
  501. *msgid* should be specified as the constant :py:const:`RES_ANY`
  502. and the method :py:meth:`result2()` should be used instead.
  503. The *all* parameter only has meaning for :py:meth:`search()` responses
  504. and is used to select whether a single entry of the search
  505. response should be returned, or to wait for all the results
  506. of the search before returning.
  507. A search response is made up of zero or more search entries
  508. followed by a search result. If *all* is 0, search entries will
  509. be returned one at a time as they come in, via separate calls
  510. to :py:meth:`result()`. If all is 1, the search response will be returned
  511. in its entirety, i.e. after all entries and the final search
  512. result have been received.
  513. For *all* set to 0, result tuples
  514. trickle in (with the same message id), and with the result types
  515. :py:const:`RES_SEARCH_ENTRY` and :py:const:`RES_SEARCH_REFERENCE`,
  516. until the final result which has a result type of :py:const:`RES_SEARCH_RESULT`
  517. and a (usually) empty data field. When all is set to 1, only one result is returned,
  518. with a result type of RES_SEARCH_RESULT, and all the result tuples
  519. listed in the data field.
  520. The *timeout* parameter is a limit on the number of seconds that the
  521. method will wait for a response from the server.
  522. If *timeout* is negative (which is the default),
  523. the method will wait indefinitely for a response.
  524. The timeout can be expressed as a floating-point value, and
  525. a value of :py:const:`0` effects a poll.
  526. If a timeout does occur, a :py:exc:`ldap.TIMEOUT` exception is raised,
  527. unless polling, in which case ``(None, None)`` is returned.
  528. The :py:meth:`result()` method returns a tuple of the form
  529. ``(result-type, result-data)``.
  530. The first element, ``result-type`` is a string, being one of
  531. these module constants:
  532. :py:const:`RES_BIND`, :py:const:`RES_SEARCH_ENTRY`,
  533. :py:const:`RES_SEARCH_REFERENCE`, :py:const:`RES_SEARCH_RESULT`,
  534. :py:const:`RES_MODIFY`, :py:const:`RES_ADD`, :py:const:`RES_DELETE`,
  535. :py:const:`RES_MODRDN`, or :py:const:`RES_COMPARE`.
  536. If *all* is :py:const:`0`, one response at a time is returned on
  537. each call to :py:meth:`result()`, with termination indicated by
  538. ``result-data`` being an empty list.
  539. See :py:meth:`search()` for a description of the search result's
  540. ``result-data``, otherwise the ``result-data`` is normally meaningless.
  541. .. py:method:: LDAPObject.result2([msgid=RES_ANY [, all=1 [, timeout=None]]]) -> 3-tuple
  542. This method behaves almost exactly like :py:meth:`result()`. But
  543. it returns a 3-tuple also containing the message id of the
  544. outstanding LDAP operation a particular result message belongs
  545. to. This is especially handy if one needs to dispatch results
  546. obtained with ``msgid=``:py:const:`RES_ANY` to several consumer
  547. threads which invoked a particular LDAP operation.
  548. .. py:method:: LDAPObject.result3([msgid=RES_ANY [, all=1 [, timeout=None]]]) -> 4-tuple
  549. This method behaves almost exactly like :py:meth:`result2()`. But it
  550. returns an extra item in the tuple, the decoded server controls.
  551. .. 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
  552. This method behaves almost exactly like :py:meth:`result3()`. But it
  553. returns an extra items in the tuple, the decoded results of an extended response.
  554. The additional arguments are:
  555. *add_ctrls* (integer flag) specifies whether response controls are returned.
  556. add_intermediates (integer flag) specifies whether response controls of
  557. intermediate search results are returned.
  558. *add_extop* (integer flag) specifies whether the response of an
  559. extended operation is returned. If using extended operations you should
  560. consider using the method :py:meth:`extop_result()` or
  561. :py:meth:`extop_s()` instead.
  562. *resp_ctrl_classes* is a dictionary mapping the OID of a response controls to a
  563. :py:class:`ldap.controls.ResponseControl` class of response controls known by the
  564. application. So the response control value will be automatically decoded.
  565. If :py:const:`None` the global dictionary :py:data:`ldap.controls.KNOWN_RESPONSE_CONTROLS`
  566. is used instead.
  567. .. py:method:: LDAPObject.search(base, scope [,filterstr='(objectClass=*)' [, attrlist=None [, attrsonly=0]]]) ->int
  568. .. py:method:: LDAPObject.search_s(base, scope [,filterstr='(objectClass=*)' [, attrlist=None [, attrsonly=0]]]) ->list|None
  569. .. py:method:: LDAPObject.search_st(base, scope [,filterstr='(objectClass=*)' [, attrlist=None [, attrsonly=0 [, timeout=-1]]]]) -> list|None
  570. .. py:method:: LDAPObject.search_ext(base, scope [,filterstr='(objectClass=*)' [, attrlist=None [, attrsonly=0 [, serverctrls=None [, clientctrls=None [, timeout=-1 [, sizelimit=0]]]]]]]) -> int
  571. .. py:method:: LDAPObject.search_ext_s(base, scope [,filterstr='(objectClass=*)' [, attrlist=None [, attrsonly=0 [, serverctrls=None [, clientctrls=None [, timeout=-1 [, sizelimit=0]]]]]]]) -> list|None
  572. Perform an LDAP search operation, with *base* as the DN of the entry
  573. at which to start the search, *scope* being one of
  574. :py:const:`SCOPE_BASE` (to search the object itself),
  575. :py:const:`SCOPE_ONELEVEL` (to search the object's immediate children), or
  576. :py:const:`SCOPE_SUBTREE` (to search the object and all its descendants).
  577. The *filterstr* argument is a string representation of the filter to apply in
  578. the search.
  579. .. seealso::
  580. :rfc:`4515` - Lightweight Directory Access Protocol (LDAP): String Representation of Search Filters.
  581. Each result tuple is of the form ``(dn, attrs)``,
  582. where *dn* is a string containing the DN (distinguished name) of the
  583. entry, and *attrs* is a dictionary containing the attributes associated
  584. with the entry. The keys of *attrs* are strings, and the associated
  585. values are lists of strings.
  586. The DN in *dn* is automatically extracted using the underlying libldap
  587. function :cfunc:`ldap_get_dn()`, which may raise an exception if the
  588. DN is malformed.
  589. If *attrsonly* is non-zero, the values of *attrs* will be meaningless
  590. (they are not transmitted in the result).
  591. The retrieved attributes can be limited with the *attrlist* parameter.
  592. If *attrlist* is :py:const:`None`, all the attributes of each entry are returned.
  593. *serverctrls* and *clientctrls* like described above.
  594. The synchronous form with timeout, :py:meth:`search_st()` or :py:meth:`search_ext_s()`,
  595. will block for at most *timeout* seconds (or indefinitely if *timeout*
  596. is negative). A :py:exc:`ldap.TIMEOUT` exception is raised if no result is received
  597. within the specified time.
  598. The amount of search results retrieved can be limited with the
  599. *sizelimit* parameter when using :py:meth:`search_ext()`
  600. or :py:meth:`search_ext_s()` (client-side search limit). If non-zero
  601. not more than *sizelimit* results are returned by the server.
  602. .. py:method:: LDAPObject.start_tls_s() -> None
  603. Negotiate TLS with server. The ``version`` attribute must have been
  604. set to :py:const:`VERSION3` (which it is by default) before calling this method.
  605. If TLS could not be started an exception will be raised.
  606. .. seealso::
  607. :rfc:`2830` - Lightweight Directory Access Protocol (v3): Extension for Transport Layer Security
  608. .. py:method:: LDAPObject.unbind() -> int
  609. .. py:method:: LDAPObject.unbind_s() -> None
  610. .. py:method:: LDAPObject.unbind_ext([, serverctrls=None [, clientctrls=None]]) -> int
  611. .. py:method:: LDAPObject.unbind_ext_s([, serverctrls=None [, clientctrls=None]]) -> None
  612. This call is used to unbind from the directory, terminate the
  613. current association, and free resources. Once called, the connection to the
  614. LDAP server is closed and the LDAP object is marked invalid.
  615. Further invocation of methods on the object will yield exceptions.
  616. *serverctrls* and *clientctrls* like described above.
  617. These methods are all synchronous in nature.
  618. .. py:method:: LDAPObject.whoami_s() -> string
  619. This synchronous method implements the LDAP "Who Am I?"
  620. extended operation.
  621. It is useful for finding out to find out which identity
  622. is assumed by the LDAP server after a SASL bind.
  623. .. seealso::
  624. :rfc:`4532` - Lightweight Directory Access Protocol (LDAP) "Who am I?" Operation
  625. Connection-specific LDAP options
  626. --------------------------------
  627. .. py:method:: LDAPObject.get_option(option) -> int|string
  628. This method returns the value of the LDAPObject option
  629. specified by *option*.
  630. .. py:method:: LDAPObject.set_option(option, invalue) -> None
  631. This method sets the value of the LDAPObject option
  632. specified by *option* to *invalue*.
  633. Object attributes
  634. -----------------
  635. If the underlying library provides enough information,
  636. each LDAP object will also have the following attributes.
  637. These attributes are mutable unless described as read-only.
  638. .. py:attribute:: LDAPObject.deref -> int
  639. Controls whether aliases are automatically dereferenced.
  640. This must be one of :py:const:`DEREF_NEVER`, :py:const:`DEREF_SEARCHING`,
  641. :py:const:`DEREF_FINDING` or :py:const:`DEREF_ALWAYS`.
  642. This option is mapped to option constant :py:const:`OPT_DEREF`
  643. and used in the underlying OpenLDAP client lib.
  644. .. py:attribute:: LDAPObject.network_timeout -> int
  645. Limit on waiting for a network response, in seconds.
  646. Defaults to :py:const:`NO_LIMIT`.
  647. This option is mapped to option constant :py:const:`OPT_NETWORK_TIMEOUT`
  648. and used in the underlying OpenLDAP client lib.
  649. .. py:attribute:: LDAPObject.protocol_version -> int
  650. Version of LDAP in use (either :py:const:`VERSION2` for LDAPv2
  651. or :py:const:`VERSION3` for LDAPv3).
  652. This option is mapped to option constant :py:const:`OPT_PROTOCOL_VERSION`
  653. and used in the underlying OpenLDAP client lib.
  654. .. note::
  655. It is highly recommended to set the protocol version after establishing
  656. a LDAP connection with :py:func:`ldap.initialize()` and before submitting
  657. the first request.
  658. .. py:attribute:: LDAPObject.sizelimit -> int
  659. Limit on size of message to receive from server.
  660. Defaults to :py:const:`NO_LIMIT`.
  661. This option is mapped to option constant :py:const:`OPT_SIZELIMIT`
  662. and used in the underlying OpenLDAP client lib. Its use is deprecated
  663. in favour of *sizelimit* parameter when using :py:meth:`search_ext()`.
  664. .. py:attribute:: LDAPObject.timelimit -> int
  665. Limit on waiting for any response, in seconds.
  666. Defaults to :py:const:`NO_LIMIT`.
  667. This option is mapped to option constant :py:const:`OPT_TIMELIMIT`
  668. and used in the underlying OpenLDAP client lib. Its use is deprecated
  669. in favour of using :py:attr:`timeout`.
  670. .. py:attribute:: LDAPObject.timeout -> int
  671. Limit on waiting for any response, in seconds.
  672. Defaults to :py:const:`NO_LIMIT`.
  673. This option is used in the wrapper module.
  674. .. _ldap-example:
  675. Example
  676. =======
  677. The following example demonstrates how to open a connection to an
  678. LDAP server using the :py:mod:`ldap` module and invoke a synchronous
  679. subtree search.
  680. >>> import ldap
  681. >>> l = ldap.initialize('ldap://localhost:1390')
  682. >>> l.search_s('ou=Testing,dc=stroeder,dc=de',ldap.SCOPE_SUBTREE,'(cn=fred*)',['cn','mail'])
  683. [('cn=Fred Feuerstein,ou=Testing,dc=stroeder,dc=de', {'cn': ['Fred Feuerstein']})]
  684. >>> r = l.search_s('ou=Testing,dc=stroeder,dc=de',ldap.SCOPE_SUBTREE,'(objectClass=*)',['cn','mail'])
  685. >>> for dn,entry in r:
  686. >>> print 'Processing',repr(dn)
  687. >>> handle_ldap_entry(entry)