Ldaptor: Twisted LDAP Library

Warnings

• breaking Ldaptor version 21.2.0 is the last release to officially support Python 3.5. Future versions, starting with 21.2.1, explicitly drop support for Python 3.5.
  Fix: Upgrade to Python 3.6 or newer to use Ldaptor versions beyond 21.2.0.
• breaking Support for Python 2 was dropped in Ldaptor version 20.1.0. All subsequent versions require Python 3.x.
  Fix: Migrate your application to Python 3 and use Ldaptor versions 20.1.0 or newer.
• gotcha When working with Ldaptor objects that represent LDAP strings (like DNs, filters, or server IPs), it is strongly recommended to use byte strings (e.g., `b'dc=example,dc=com'`) rather than unicode strings, especially for compatibility and protocol-level operations.
  Fix: Ensure all string literals passed to Ldaptor objects are prefixed with `b` for byte strings. Encode string variables to bytes using `.encode('utf-8')`.
• deprecated The `setup.py` file and `sdist` (source distribution) are deprecated for packaging Ldaptor, with `setup.py` planned for removal in a future release. PyPI releases are now managed via GitHub Actions and built with `pep517` for `whl` packages.
  Fix: For consuming Ldaptor, prefer `pip install ldaptor` which uses `whl` distributions. For developers/packagers, adapt build processes away from relying on `setup.py` directly or `sdist`.
• gotcha Prior to version 21.2.0, there were `ModuleNotFoundError` issues related to `cStringIO` in the `ldaptor-ldap2pdns` script, indicating potential compatibility problems with Python 3's `io` module.
  Fix: Upgrade to Ldaptor 21.2.0 or newer to resolve `cStringIO`-related import errors.
• gotcha By default, the `__repr__` method of `ldaptor.protocols.pureldap.LDAPBindRequest` can print the BIND password in logs. This is a security risk for applications logging protocol details.
  Fix: When using LDAP proxies or debugging, be aware of this. For proxies, consider subclassing `ldaptor.protocols.ldap.proxybase.ProxyBase` and patching the `__repr__` of `LDAPBindRequest` to mask sensitive information, as shown in Ldaptor's documentation for LDAP proxies.

Install

• pip install ldaptor Install Ldaptor

Imports

• LDAPClientCreator

  from ldaptor.protocols.ldap import ldapconnector

• LDAPClient

  from ldaptor.protocols.ldap import ldapclient

• LDAPEntry

  from ldaptor.protocols.ldap import ldapsyntax

• reactor, defer

  from twisted.internet import reactor, defer

Quickstart

This quickstart demonstrates how to connect to an LDAP server, bind with credentials, and perform a basic search operation using Ldaptor and Twisted's asynchronous reactor. The example uses environment variables for sensitive connection details, falling back to defaults if not set. Remember to replace placeholder values with your actual LDAP server details.

import os
from twisted.internet import reactor, defer
from ldaptor.protocols.ldap import ldapclient, ldapsyntax, ldapconnector

@defer.inlineCallbacks
def example():
    # Note: For production, load sensitive data securely (e.g., from environment variables).
    # It is recommended to use byte strings for ldaptor objects.
    server_ip = os.environ.get('LDAP_SERVER_IP', '127.0.0.1').encode('utf-8')
    basedn = os.environ.get('LDAP_BASE_DN', 'dc=example,dc=com').encode('utf-8')
    binddn = os.environ.get('LDAP_BIND_DN', 'cn=admin,dc=example,dc=com').encode('utf-8')
    bindpw = os.environ.get('LDAP_BIND_PASSWORD', 'secret').encode('utf-8')
    query = os.environ.get('LDAP_QUERY', '(objectClass=*)').encode('utf-8')

    # Create an LDAP client creator
    c = ldapconnector.LDAPClientCreator(reactor, ldapclient.LDAPClient)
    
    # Define overrides for connecting to the LDAP server
    overrides = {basedn: (server_ip, 389)}

    # Connect to the LDAP server
    client = yield c.connect(basedn, overrides=overrides)
    print(f"Connected to LDAP server at {server_ip.decode('utf-8')}")

    # Bind to the LDAP server
    yield client.bind(binddn, bindpw)
    print(f"Bound as {binddn.decode('utf-8')}")

    # Perform a search
    o = ldapsyntax.LDAPEntry(client, basedn)
    results = yield o.search(filterText=query)
    print(f"Found {len(results)} entries for query '{query.decode('utf-8')}'")
    
    # Print LDIF for each result
    for entry in results:
        print(entry.getLDIF())

    print("LDAP operations complete.")


if __name__ == '__main__':
    df = example()
    df.addErrback(lambda err: err.printTraceback())
    df.addCallback(lambda _: reactor.stop())
    reactor.run()