ldap3 - LDAP Client Library

Warnings

• gotcha The library was formerly known as `python3-ldap` and was renamed to `ldap3` to avoid confusion with the `python-ldap` library. Users migrating from `python3-ldap` or older `python-ldap` installations should be aware.
  Fix: Ensure you are installing and importing the `ldap3` package. If you have `python-ldap` installed, be mindful of potential conflicts due to similar names but different APIs.
• gotcha LDAP protocol strictly uses UTF-8 for string values. While `ldap3` attempts to handle encoding, mismatches between your environment's default encoding and required UTF-8 can lead to issues. Explicit encoding/decoding may be necessary.
  Fix: Be explicit about string encoding when necessary. Use `set_config_parameter('DEFAULT_ENCODING', 'my_encoding')` if your input encoding is not UTF-8 and differs from your system default. Ensure data retrieved is handled as UTF-8.
• gotcha Different connection strategies (e.g., `SYNC`, `ASYNC`, `RESTARTABLE`, `REUSABLE`, `SAFE_SYNC`, `SAFE_RESTARTABLE`) have different return value semantics. Synchronous strategies (e.g., `SYNC`) typically return booleans for success/failure, while asynchronous strategies (e.g., `ASYNC`) return a `message_id`. Incorrectly handling these return types is a common pitfall.
  Fix: Always check the documentation for the specific connection strategy you are using to understand its return values. For `ASYNC`, you typically need to call `get_response()` separately to retrieve the operation result. For multi-threaded programs, use `SAFE_SYNC` or `SAFE_RESTARTABLE`.
• gotcha Special characters in user-provided input for LDAP queries (e.g., `*`, `(`, `)`, `\`, NUL) must be properly escaped to prevent syntax errors and security vulnerabilities (like LDAP injection).
  Fix: Always escape user inputs before using them in LDAP filters or DNs. `ldap3` provides utility functions for this (e.g., `ldap3.utils.conv.escape_filter_chars`, `ldap3.utils.conv.escape_rdn_chars`). Never directly concatenate unescaped user input into LDAP queries.
• gotcha When using `ldap3` with `pyasn1` versions greater than `0.6.0`, a `DeprecationWarning` regarding `typeMap` vs. `TYPE_MAP` may be triggered. While typically harmless, it can clutter logs. This issue has been addressed in PR #983.
  Fix: Check for `ldap3` updates that include the fix for `pyasn1` compatibility. If warning persists and is disruptive, you may need to filter the warning or consider pinning `pyasn1 < 0.6.0` if feasible for your project, though this is not generally recommended for security/maintenance reasons.

Install

• pip install ldap3 Install stable version
• pip install ldap3[gssapi] Install with Kerberos (GSSAPI) support
• pip install ldap3[winkerberos] Install with Kerberos (winkerberos) support for Windows

Imports

• Server

  from ldap3 import Server

• Connection

  from ldap3 import Connection

• Tls

  from ldap3 import Tls

• ANONYMOUS

  from ldap3 import ANONYMOUS

  Constants like ANONYMOUS, SIMPLE, SASL are directly in the ldap3 namespace, not under an 'AUTH_' prefix.
• STRATEGY_SYNC

  from ldap3 import SYNC

  Connection strategies are typically imported directly by their short names (e.g., SYNC, ASYNC, RESTARTABLE).

Quickstart

This example demonstrates how to establish a connection to an LDAP server, perform a simple bind with credentials (or anonymously), and execute a search operation. It uses environment variables for sensitive configuration details. The `raise_exceptions=True` parameter is added to the `Connection` to ensure LDAP operation failures are surfaced as Python exceptions.

import os
from ldap3 import Server, Connection, SYNC, ANONYMOUS, SUBTREE

# Configuration from environment variables for security and flexibility
LDAP_SERVER_URI = os.environ.get('LDAP_SERVER_URI', 'ldap://localhost:389')
LDAP_BIND_DN = os.environ.get('LDAP_BIND_DN', 'cn=admin,dc=example,dc=com')
LDAP_BIND_PASSWORD = os.environ.get('LDAP_BIND_PASSWORD', 'adminpassword')
LDAP_SEARCH_BASE = os.environ.get('LDAP_SEARCH_BASE', 'dc=example,dc=com')
LDAP_SEARCH_FILTER = os.environ.get('LDAP_SEARCH_FILTER', '(objectClass=person)')
LDAP_SEARCH_ATTRIBUTES = os.environ.get('LDAP_SEARCH_ATTRIBUTES', 'cn,mail').split(',')

def ldap_connect_and_search():
    try:
        # Define the LDAP server
        s = Server(LDAP_SERVER_URI)

        # Establish a connection. auto_bind=True performs the bind operation immediately.
        # authentication=ANONYMOUS can be used if no credentials are required.
        # For authenticated bind:
        # c = Connection(s, user=LDAP_BIND_DN, password=LDAP_BIND_PASSWORD, client_strategy=SYNC, auto_bind=True)
        c = Connection(s, user=LDAP_BIND_DN, password=LDAP_BIND_PASSWORD, client_strategy=SYNC, auto_bind=True, raise_exceptions=True)

        print(f"Connection status: {c.bound}")

        # Perform a search operation
        # search_base: The base DN for the search
        # search_filter: The LDAP filter string
        # search_scope: The scope of the search (e.g., SUBTREE, BASE, LEVEL)
        # attributes: List of attributes to retrieve, or ALL_ATTRIBUTES, ALL_OPERATIONAL_ATTRIBUTES
        c.search(LDAP_SEARCH_BASE, LDAP_SEARCH_FILTER, search_scope=SUBTREE, attributes=LDAP_SEARCH_ATTRIBUTES)

        # Process the search results
        print(f"Found {len(c.entries)} entries:")
        for entry in c.entries:
            print(f"  DN: {entry.entry_dn}")
            for attr in LDAP_SEARCH_ATTRIBUTES:
                if hasattr(entry, attr):
                    print(f"    {attr}: {getattr(entry, attr).value}")

    except Exception as e:
        print(f"An LDAP error occurred: {e}")
    finally:
        if 'c' in locals() and c.bound:
            c.unbind()
            print("Connection unbound.")

if __name__ == '__main__':
    ldap_connect_and_search()