feat(connector): add on-prem Active Directory (LDAP) HR connector

[cyberdima]

CDK Python connector querying AD over LDAP/LDAPS (ldap3). Sibling of ms-entra — same class_people/identity_inputs Silver contract, different transport. sAMAccountName → sam_account identity signal reconciles on-prem AD ↔ cloud Entra ↔ self-hosted Git.

• source_active_directory/: AbstractSource, ldap_client, users stream (paged search, objectGUID-keyed, privacy allowlist)
• dbt/: bronze_promoted, snapshot, fields_history, identity_inputs, to_class_people (mirror of ms_entra__* models)
• docs/domain/connector/HR_IDENTITY_CONNECTOR_GUIDE.md: agent-facing recipe for HR/identity connector authoring (CDK-for-non-HTTP pattern)
• secrets/connectors/active-directory.yaml.example: K8s Secret template

Summary by CodeRabbit

• New Features
  • Added an on-premises Active Directory connector with LDAP/LDAPS user synchronization.
  • Produces unified people profiles plus identity signals, including account status and manager relationships.
  • Adds field history and more complete manager updates (including reassignment and removal handling) for downstream identity processing.
• Documentation
  • Added an agent-facing connector authoring guide for HR/identity “Silver contract” connectors, including CDK recipe and checklist.
  • Expanded Active Directory connector docs and added a Kubernetes Secret example.

[coderabbitai]

Warning

Review limit reached

@cyberantonz, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 48 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 279354df-0655-49ab-9db4-bfaf8d2657b9

📥 Commits

Reviewing files that changed from the base of the PR and between 151bdcc and 57157d7.

📒 Files selected for processing (2)

• src/ingestion/connectors/hr-directory/active-directory/README.md
• src/ingestion/connectors/hr-directory/active-directory/dbt/active_directory__manager_identity_inputs.sql

📝 Walkthrough

Walkthrough

Adds an Airbyte LDAP/LDAPS Active Directory connector with paged Bronze user extraction, normalized identity fields, SCD2 history, class_people mapping, manager relationships, identity inputs, deployment configuration, and authoring documentation.

Changes

Active Directory HR Connector

Layer / File(s)	Summary
Connector runtime and configuration docs/domain/connector/..., src/ingestion/connectors/hr-directory/active-directory/..., src/ingestion/secrets/...	Adds the Airbyte source, configuration schema, packaging, Docker image, deployment descriptor, Kubernetes Secret example, and connector documentation.
LDAP transport and Bronze users stream src/ingestion/connectors/hr-directory/active-directory/source_active_directory/...	Connects to LDAP/LDAPS, normalizes GUIDs, timestamps, and account status, then emits paged Active Directory users with a Bronze JSON schema.
Silver snapshots and identity mappings src/ingestion/connectors/hr-directory/active-directory/dbt/..., src/ingestion/silver/_shared/...	Adds Bronze promotion, snapshots, field history, class_people mapping, identity and manager inputs, schema tests, and shared dbt dependency references.

Estimated code review effort: 4 (Complex) | ~45 minutes

Possibly related PRs

• constructorfabric/insight#1312: Adds a similar shared identity_inputs.sql dependency reference for another connector.
• constructorfabric/insight#1892: Overlaps on shared dbt dependency wiring for HR/person identity models.

Suggested reviewers: mitasovr

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: adding an on-prem Active Directory LDAP HR connector.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/ad-hr-connector

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 10

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/domain/connector/HR_IDENTITY_CONNECTOR_GUIDE.md`:
- Line 30: Add the `text` language identifier to both fenced code blocks in the
HR identity connector guide, including the blocks around the referenced
locations, so the diagrams satisfy markdownlint MD040.

In
`@src/ingestion/connectors/hr-directory/active-directory/dbt/active_directory__manager_identity_inputs.sql`:
- Around line 41-43: Update the manager change filtering in the active-directory
manager identity inputs query so empty managerDn changes are retained as DELETE
events rather than excluded. Emit DELETE rows for both parent_email and
parent_id relationship value types when managerDn becomes empty, while
preserving existing behavior for non-empty manager updates.
- Around line 38-41: Update the manager identity input query around the history
CTE and manager join to include changes to a manager’s mail or
userPrincipalName, not only managerDn changes. Fan those email-history events
out to every user whose current managerDn references the changed manager, while
preserving the existing parent_email output and direct-report mapping.

In
`@src/ingestion/connectors/hr-directory/active-directory/dbt/active_directory__to_class_people.sql`:
- Around line 37-40: Update the manager mapping around the manager_person_id
projection to leave manager_person_id null instead of selecting mgr.id, since
mgr.id is an AD source identifier. Preserve the existing parent_id and
parent_email identity signals so manager relationships are resolved through
identity resolution.

In
`@src/ingestion/connectors/hr-directory/active-directory/dbt/active_directory__users_snapshot.sql`:
- Around line 12-16: Update the snapshot’s check_cols configuration to include
managerDn alongside the other tracked user fields, ensuring manager-only changes
create a new version for active_directory__users_fields_history and reach
active_directory__manager_identity_inputs.

In `@src/ingestion/connectors/hr-directory/active-directory/pyproject.toml`:
- Around line 1-3: Update the build configuration in pyproject.toml to add the
required cf-studio-path setting with the value .cf-studio, preserving the
existing build-system configuration.

In
`@src/ingestion/connectors/hr-directory/active-directory/source_active_directory/ldap_client.py`:
- Around line 64-65: Update the configuration parsing for ad_use_ssl before
constructing Tls or the LDAP server so string values "true" and "false" are
converted to booleans, while invalid values are rejected. Preserve the default
of true when the setting is absent, and ensure the normalized value controls
LDAPS selection and port 636 behavior.
- Line 65: Update the TLS configuration in the LDAP client’s SSL setup to
require certificate and hostname validation instead of using Tls(validate=0).
Configure the trusted CA bundle through the existing connector configuration or
mounted certificate path so private AD certificates are supported without
falling back to CERT_NONE.

In
`@src/ingestion/connectors/hr-directory/active-directory/source_active_directory/source.py`:
- Around line 50-56: The check_connection() validation must reject empty
normalized insight_source_id and insight_tenant_id values before records are
emitted. In source.py, retrieve and trim both identity fields and return the
existing failure response when either is empty; in spec.json, add minLength: 1
to both identity field definitions so configuration validation enforces the same
requirement.
- Around line 73-91: Update the connection probe in check_connection to avoid
treating expected LDAP size limits as failures: use BASE search scope with an
(objectClass=*) filter, or explicitly handle LDAPSizeLimitExceededResult as
success. Preserve failure handling for other LDAP errors and unreadable search
bases.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f8f791fe-5560-49c3-b25b-e935068c3750

📥 Commits

Reviewing files that changed from the base of the PR and between 48f410e and 4602f94.

📒 Files selected for processing (21)

• docs/domain/connector/HR_IDENTITY_CONNECTOR_GUIDE.md
• src/ingestion/connectors/hr-directory/active-directory/Dockerfile
• src/ingestion/connectors/hr-directory/active-directory/README.md
• src/ingestion/connectors/hr-directory/active-directory/dbt/active_directory__bronze_promoted.sql
• src/ingestion/connectors/hr-directory/active-directory/dbt/active_directory__identity_inputs.sql
• src/ingestion/connectors/hr-directory/active-directory/dbt/active_directory__manager_identity_inputs.sql
• src/ingestion/connectors/hr-directory/active-directory/dbt/active_directory__to_class_people.sql
• src/ingestion/connectors/hr-directory/active-directory/dbt/active_directory__users_fields_history.sql
• src/ingestion/connectors/hr-directory/active-directory/dbt/active_directory__users_snapshot.sql
• src/ingestion/connectors/hr-directory/active-directory/dbt/schema.yml
• src/ingestion/connectors/hr-directory/active-directory/descriptor.yaml
• src/ingestion/connectors/hr-directory/active-directory/pyproject.toml
• src/ingestion/connectors/hr-directory/active-directory/source_active_directory/__init__.py
• src/ingestion/connectors/hr-directory/active-directory/source_active_directory/ldap_client.py
• src/ingestion/connectors/hr-directory/active-directory/source_active_directory/source.py
• src/ingestion/connectors/hr-directory/active-directory/source_active_directory/spec.json
• src/ingestion/connectors/hr-directory/active-directory/source_active_directory/streams/__init__.py
• src/ingestion/connectors/hr-directory/active-directory/source_active_directory/streams/users.py
• src/ingestion/secrets/connectors/active-directory.yaml.example
• src/ingestion/silver/_shared/class_people.sql
• src/ingestion/silver/_shared/identity_inputs.sql

[github-actions]

⚠️ Regenerate the connectors-ddl snapshot

This PR changes src/ingestion/**. If your change affects any
bronze / silver / gold schema, regenerate the committed DDL snapshot
and include it in this PR:

cd src/ingestion/scripts/bootstrap-db
set -a; source pins.env; source .env; set +a
./bootstrap-db.sh connectors-config.yaml   # fresh ClickHouse 25.7.5
./dump-ddl.sh                              # writes scripts/connectors-ddl/*.sql

Commit the resulting scripts/connectors-ddl/*.sql diff. If nothing
changed, no snapshot update is needed. (Regeneration is manual for now.)

[coderabbitai]

Actionable comments posted: 4

🧹 Nitpick comments (2)

src/ingestion/connectors/hr-directory/active-directory/source_active_directory/streams/users.py (1)

163-195: 🗄️ Data Integrity & Integration | 🔵 Trivial | 💤 Low value

Consider requiring tenant_id/source_id in the schema, matching the stated framework-field contract.

The docstring at line 115-117 in source.py's CDK counterpart states tenant_id/source_id/unique_key are all mandatory framework fields, but only unique_key and id are in required here. Since these are always populated in _to_record, this is non-blocking, but adding them closes a latent gap if the record-building logic ever changes.

♻️ Proposed fix

-            "required": ["unique_key", "id"],
+            "required": ["unique_key", "id", "tenant_id", "source_id"],

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@src/ingestion/connectors/hr-directory/active-directory/source_active_directory/streams/users.py`
around lines 163 - 195, Update the get_json_schema method’s required list to
include tenant_id and source_id alongside unique_key and id, matching the
framework-field contract and the fields populated by _to_record.

src/ingestion/connectors/hr-directory/active-directory/source_active_directory/source.py (1)

101-106: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Silent except Exception: pass on connection cleanup in both files. Both files swallow all unbind exceptions with no logging; the # noqa: BLE001 doesn't suppress Ruff's S110 (try-except-pass) hint, so this still surfaces in lint.

• src/ingestion/connectors/hr-directory/active-directory/source_active_directory/source.py#L101-L106: log the unbind exception at debug level (or extend the noqa to cover S110) instead of silently passing.
• src/ingestion/connectors/hr-directory/active-directory/source_active_directory/streams/users.py#L157-L161: apply the same debug-logging fix to the conn.unbind() cleanup in read_records.

♻️ Proposed fix (apply to both sites)

-                try:
-                    conn.unbind()
-                except Exception:  # noqa: BLE001 — best-effort cleanup
-                    pass
+                try:
+                    conn.unbind()
+                except Exception:  # noqa: BLE001 — best-effort cleanup
+                    logger.debug("LDAP unbind failed", exc_info=True)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@src/ingestion/connectors/hr-directory/active-directory/source_active_directory/source.py`
around lines 101 - 106, The conn.unbind() cleanup handlers in source.py lines
101-106 and users.py lines 157-161 silently swallow exceptions and trigger S110.
Update both cleanup blocks to log unbind failures at debug level while
preserving best-effort cleanup and exception suppression; use the surrounding
source flow and read_records method as anchors.

Source: Linters/SAST tools

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In
`@src/ingestion/connectors/hr-directory/active-directory/dbt/active_directory__manager_identity_inputs.sql`:
- Around line 71-84: Deduplicate the rows produced by manager_email_changes
before they are emitted, grouping or applying distinctness by report,
updated_at, and resolved manager_email so simultaneous mail and
userPrincipalName history events yield one event. Preserve the existing coalesce
resolution and joins, while retaining separate rows when the report, timestamp,
or resolved email differs.
- Around line 71-84: Update manager_email_changes and the downstream
event-generation logic so a manager with both mail and userPrincipalName empty
produces a DELETE event for each affected direct report. Ensure the DELETE
clears the existing parent_email instead of being removed by the final non-empty
filter, while preserving current behavior for non-empty manager emails.
- Around line 52-53: Update all three manager joins in the active-directory
manager identity inputs query, including the joins around current_users and the
referenced location, to require matching tenant_id and source_id in addition to
the existing manager identifier predicate. Preserve the current join behavior
within the same tenant and source while preventing cross-tenant or cross-source
matches.

In `@src/ingestion/connectors/hr-directory/active-directory/README.md`:
- Around line 90-93: Update the privacy statement in the README to remove the
inaccurate “or other PII” claim. Describe that the explicit allowlist still
collects required identity fields, while excluding non-required fields such as
photos, postal addresses, and phone numbers.

---

Nitpick comments:
In
`@src/ingestion/connectors/hr-directory/active-directory/source_active_directory/source.py`:
- Around line 101-106: The conn.unbind() cleanup handlers in source.py lines
101-106 and users.py lines 157-161 silently swallow exceptions and trigger S110.
Update both cleanup blocks to log unbind failures at debug level while
preserving best-effort cleanup and exception suppression; use the surrounding
source flow and read_records method as anchors.

In
`@src/ingestion/connectors/hr-directory/active-directory/source_active_directory/streams/users.py`:
- Around line 163-195: Update the get_json_schema method’s required list to
include tenant_id and source_id alongside unique_key and id, matching the
framework-field contract and the fields populated by _to_record.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: b1e64a49-5c4b-46db-9c91-1d7b7843834a

📥 Commits

Reviewing files that changed from the base of the PR and between 4602f94 and 151bdcc.

📒 Files selected for processing (21)

• docs/domain/connector/HR_IDENTITY_CONNECTOR_GUIDE.md
• src/ingestion/connectors/hr-directory/active-directory/Dockerfile
• src/ingestion/connectors/hr-directory/active-directory/README.md
• src/ingestion/connectors/hr-directory/active-directory/dbt/active_directory__bronze_promoted.sql
• src/ingestion/connectors/hr-directory/active-directory/dbt/active_directory__identity_inputs.sql
• src/ingestion/connectors/hr-directory/active-directory/dbt/active_directory__manager_identity_inputs.sql
• src/ingestion/connectors/hr-directory/active-directory/dbt/active_directory__to_class_people.sql
• src/ingestion/connectors/hr-directory/active-directory/dbt/active_directory__users_fields_history.sql
• src/ingestion/connectors/hr-directory/active-directory/dbt/active_directory__users_snapshot.sql
• src/ingestion/connectors/hr-directory/active-directory/dbt/schema.yml
• src/ingestion/connectors/hr-directory/active-directory/descriptor.yaml
• src/ingestion/connectors/hr-directory/active-directory/pyproject.toml
• src/ingestion/connectors/hr-directory/active-directory/source_active_directory/__init__.py
• src/ingestion/connectors/hr-directory/active-directory/source_active_directory/ldap_client.py
• src/ingestion/connectors/hr-directory/active-directory/source_active_directory/source.py
• src/ingestion/connectors/hr-directory/active-directory/source_active_directory/spec.json
• src/ingestion/connectors/hr-directory/active-directory/source_active_directory/streams/__init__.py
• src/ingestion/connectors/hr-directory/active-directory/source_active_directory/streams/users.py
• src/ingestion/secrets/connectors/active-directory.yaml.example
• src/ingestion/silver/_shared/class_people.sql
• src/ingestion/silver/_shared/identity_inputs.sql

🚧 Files skipped from review as they are similar to previous changes (14)

• src/ingestion/silver/_shared/class_people.sql
• src/ingestion/connectors/hr-directory/active-directory/source_active_directory/init.py
• src/ingestion/connectors/hr-directory/active-directory/Dockerfile
• src/ingestion/secrets/connectors/active-directory.yaml.example
• src/ingestion/connectors/hr-directory/active-directory/dbt/active_directory__bronze_promoted.sql
• src/ingestion/connectors/hr-directory/active-directory/pyproject.toml
• docs/domain/connector/HR_IDENTITY_CONNECTOR_GUIDE.md
• src/ingestion/silver/_shared/identity_inputs.sql
• src/ingestion/connectors/hr-directory/active-directory/dbt/active_directory__users_snapshot.sql
• src/ingestion/connectors/hr-directory/active-directory/dbt/schema.yml
• src/ingestion/connectors/hr-directory/active-directory/dbt/active_directory__identity_inputs.sql
• src/ingestion/connectors/hr-directory/active-directory/source_active_directory/spec.json
• src/ingestion/connectors/hr-directory/active-directory/source_active_directory/ldap_client.py
• src/ingestion/connectors/hr-directory/active-directory/descriptor.yaml