Quick Start Guide
Relevant source files
The following files were used as context for generating this wiki page:
The flext-tap-ldap project is a Singer Tap designed for extracting data from LDAP Directory Services. It leverages the FLEXT framework to provide a standardized, typed integration for enterprise ETL (Extract, Transform, Load) pipelines. The tap supports traditional LDAP server queries as well as LDIF (LDAP Data Interchange Format) file processing and analysis.
This guide provides the necessary information to configure, initialize, and execute the tap within a Singer-compliant environment. It covers core components such as the FlextTapLdapTap class, the LDAP client infrastructure, and the dual-mode operation for both live directory services and static LDIF files.
Sources: README.md:1-12, pyproject.toml:23-33, src/flext_tap_ldap/tap.py:16-25
Installation and Core Metadata
The project is built for Python 3.13 and uses hatchling as its build backend. It relies on the flext-core, flext-ldap, and flext-meltano libraries for its underlying functionality.
| Attribute | Value |
|---|---|
| Package Name | flext-tap-ldap |
| Version | 0.12.0-dev |
| CLI Commands | flext-tap-ldap, tap-ldap |
| Python Version | 3.13+ |
Sources: pyproject.toml:9-12, pyproject.toml:23-45, pyproject.toml:117-118
System Architecture
The tap operates by consolidating stream discovery and client integration into a unified FlextTapLdapTap class. This class manages the connection to LDAP servers or the ingestion of LDIF files.
Data Flow Overview
The following diagram illustrates the high-level flow from configuration to Singer-formatted output.
The flow demonstrates how the tap branches between discovery mode (outputting a catalog) and sync mode (streaming records).
Sources: src/flext_tap_ldap/tap.py:117-150, src/flext_tap_ldap/tap.py:228-260
Configuration Options
The tap is configured via a JSON file. The configuration schema includes settings for server connectivity, authentication, and specific processing flags for LDIF data.
| Property | Type | Default | Description |
|---|---|---|---|
host | string | N/A | LDAP server host address. |
port | integer | 389 | LDAP server port. |
bind_dn | string | N/A | Distinguished Name for authentication. |
password | string | N/A | Password for LDAP authentication. |
base_dn | string | N/A | The root DN for search operations. |
use_ssl | boolean | false | Enables SSL/LDAPS connection. |
page_size | integer | 1000 | Results per page for paged searches. |
enable_ldif_streams | boolean | false | Enables processing of local LDIF files. |
ldif_directory | string | N/A | Path to directory containing LDIF files. |
Sources: src/flext_tap_ldap/tap.py:59-106, src/flext_tap_ldap/client.py:48-52
Execution Modes
The tap supports the standard Singer CLI interface, allowing for discovery and synchronization.
Discovery Mode
To discover available streams and their schemas, use the --discover flag. The tap discovers standard LDAP streams (Users, Groups, Organizational Units, Schema) and optional LDIF streams if configured.
tap-ldap --config config.json --discover
Sources: src/flext_tap_ldap/tap.py:223-238
Sync Mode
To extract data, provide the configuration and the catalog (optionally with a state file for incremental sync).
tap-ldap --config config.json --catalog catalog.json [--state state.json]
Sources: src/flext_tap_ldap/tap.py:276-285
LDAP Client Infrastructure
The LDAPClient provides a testing-convenience wrapper around the flext-ldap core. It handles server URI construction, health checks, and synchronous search operations.
Sequence Diagram: LDAP Search
The following diagram shows the internal delegation during a search request.
The sequence demonstrates how the LDAPClient uses ClientSupport utilities to normalize inputs and outputs before returning them to the Tap execution layer.
Sources: src/flext_tap_ldap/client.py:100-117, src/flext_tap_ldap/client.py:218-245, src/flext_tap_ldap/_utilities/client_support.py:175-188
LDIF Processing and Analysis
When enable_ldif_streams is set to true, the tap utilizes the flext-ldif library to process local files. Two specific streams are provided:
- LdifStream: Extracts entries from LDIF files as Singer records.
- LdifAnalysisStream: Provides summary statistics including entry counts and object class distributions.
Processor Components
The u.TapLdap namespace contains inner classes for handling LDIF data:
- Processor: Parses LDIF content or files and yields entries.
- Validator: Validates LDIF entries against LDAP schemas.
- Transformer: Applies attribute mappings, additions, or removals to entries.
Sources: src/flext_tap_ldap/ldif_streams.py:47-66, src/flext_tap_ldap/ldif_streams.py:166-188, src/flext_tap_ldap/_utilities/_processor.py:144-165, src/flext_tap_ldap/_utilities/_processor.py:317-330, src/flext_tap_ldap/_utilities/_processor.py:372-385
Summary
The flext-tap-ldap provides a robust implementation of the Singer protocol for LDAP and LDIF data sources. By utilizing the FlextTapLdapTap abstractions and a specialized LDAPClient, it ensures that enterprise directory data is extracted in a clean, JSON-normalized format compatible with modern data warehouses. Use the --discover command to begin identifying your directory structure and the configuration schema to tailor the connection to your environment.
Sources: src/flext_tap_ldap/tap.py:21-40, src/flext_tap_ldap/client.py:27-35