LDAP Client Connection

Relevant source files

The following files were used as context for generating this wiki page:

• src/flext_target_ldap/_utilities/client.py
• src/flext_target_ldap/settings.py
• src/flext_target_ldap/api.py
• src/flext_target_ldap/_models/sinks.py
• src/flext_target_ldap/models.py
• src/flext_target_ldap/_utilities/settings.py

The LDAP Client Connection module provides an enterprise-grade interface for interacting with LDAP directories within the flext-target-ldap project. It serves as a delegation layer to the flext-ldap API, abstracting the complexities of connection management, authentication, and standard LDAP operations such as adding, modifying, deleting, and searching entries.

The primary component of this system is the FlextTargetLdapClient, which handles the lifecycle of LDAP sessions and converts project-specific data structures into the LDIF-compatible formats required by the underlying directory server.

Architecture and Components

The connection architecture is built on a delegation model where the target client consumes configuration from FlextTargetLdapSettings and executes operations via the flext-ldap core library.

Client Lifecycle and Workflow

The FlextTargetLdapClient manages the state of the connection, including the host, port, credentials, and SSL/TLS settings. It implements a connect-execute-disconnect pattern for most operations to ensure resource safety.

Key Classes and Data Structures

Class	Description	Source
FlextTargetLdapClient	Enterprise LDAP client delegating operations to flext-ldap API.	src/flext_target_ldap/_utilities/client.py:19
FlextTargetLdapSettings	Pydantic model for validating and normalizing connection and operation parameters.	src/flext_target_ldap/settings.py:27
ConnectionConfig	Domain model within m.Ldap defining host, port, and authentication details.	src/flext_target_ldap/settings.py:51

Connection Configuration

Connection settings are governed by the FlextTargetLdapSettings class, which uses an environment prefix TARGET_LDAP_. The system supports both flat Singer-style configurations and nested canonical shapes through a normalization process.

Configuration Parameters

Parameter	Type	Default	Description
host	str	localhost	LDAP server hostname or IP.
port	int	389	Connection port (typically 389 or 636).
use_ssl	bool	False	Enables LDAPS protocol.
bind_dn	str	None	Distinguished Name for authentication.
bind_password	str	None	Password for the bind DN.
timeout	int	30	Connection timeout in seconds.

Sources: src/flext_target_ldap/settings.py:52-82, src/flext_target_ldap/settings.py:109-122

URI Construction

The client dynamically constructs the server URI based on the use_ssl flag:

• ldaps://<host>:<port> when SSL is enabled.
• ldap://<host>:<port> when SSL is disabled.

Sources: src/flext_target_ldap/_utilities/client.py:149-152

Operation Logic

The client provides high-level methods that wrap raw LDAP commands into project-specific Results (p.Result).

Entry Management

The client handles the conversion of Singer record payloads into LDIF entries. This includes:

1. Attribute Conversion: Converting various JSON types into string sequences via to_str_values.
2. DN Construction: Building the Distinguished Name based on stream type (e.g., uid=... for users, cn=... for groups).
3. Conflict Resolution: Sinks utilize the client to check for entry existence and decide between add_entry or modify_entry based on the update_existing_entries setting.

Modification Handling

Modification operations use the REPLACE change type for all provided attributes. The _build_modify_changes method transforms a dictionary of attributes into the format expected by the flext-ldap modify method: (c.Ldap.ModifyOperation.REPLACE, values).

Sources: src/flext_target_ldap/_utilities/client.py:61-75, src/flext_target_ldap/_utilities/client.py:277-302

Data Models and Validation

The project uses a unified model approach for LDAP entities to ensure data integrity before sending operations to the server.

LDAP Entry Model

The m.TargetLdap.Entry model validates business rules, such as:

• Ensuring the DN contains valid attribute=value pairs.
• Verifying that person object classes have required attributes like sn (Surname) and cn (Common Name).
• Ensuring groupOfNames entries contain at least one member.

Sources: src/flext_target_ldap/models.py:94-177

Conclusion

The LDAP Client Connection module provides a robust, settings-driven interface for directory operations. By abstracting the flext-ldap API and providing automated DN construction and attribute normalization, it enables the project to handle complex data integration tasks—such as synchronizing users, groups, and organizational units—with consistent error handling and validation logic.