LDAP / Active Directory Connector Guide

The LDAP / Active Directory connector gives Tealfabric workflows a safe and repeatable way to search directory records, authenticate users, and manage entries without writing directory-specific integration code in each process. This guide focuses on production setup, practical execution patterns, and reliability considerations so your identity-related automations remain stable over time.

When to use this connector

Use this connector when your workflow must look up users or groups, verify credentials against enterprise directory services, or apply controlled entry updates from approved automation. It is especially useful for account lifecycle workflows, access approvals, and identity synchronization pipelines. Defining filters, base DN scope, and attribute expectations upfront helps avoid brittle directory logic later.

Prerequisites

Before configuring the integration, confirm your directory endpoint, base DN, and service account permissions with your identity administrator. In production, prefer encrypted transport (ldaps://) and ensure the bind account only has the minimum permissions needed for your workflow. A scoped service account significantly reduces risk when running write operations.

Configuration reference

Connector configuration is stored once and reused during execution. Keep credentials in secure storage and rotate them according to your security policy.

• server_url (required): LDAP/LDAPS server endpoint, for example ldaps://dc1.example.com:636.
• base_dn (required): Base distinguished name for searches and operations, for example dc=example,dc=com.
• bind_dn (required): Service account DN or principal used for bind authentication.
• bind_password (required): Password for the bind account.
• timeout_seconds (optional): Request timeout for directory operations.

Search directory records

The search operation is commonly used to resolve users, groups, and membership attributes during workflow execution. Keep filters specific and attribute lists minimal to improve performance and reduce unnecessary payload size.

const baseUrl = "https://api.example.com/api/v1";
const tenantId = "<TENANT_ID>";
const apiKey = "<API_KEY>";

type DirectoryEntry = {
  dn: string;
  cn?: string[];
  mail?: string[];
  memberOf?: string[];
};

async function searchDirectory(
  integrationId: string,
  userEmail: string
): Promise<DirectoryEntry[]> {
  const response = await fetch(
    `${baseUrl}/integrations/${encodeURIComponent(integrationId)}/execute`,
    {
      method: "POST",
      headers: {
        "X-API-Key": apiKey,
        "X-Tenant-ID": tenantId,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        operation: "search",
        filter: `(mail=${userEmail})`,
        scope: "sub",
        attributes: ["cn", "mail", "memberOf"],
      }),
    }
  );

  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  const payload = (await response.json()) as { entries?: DirectoryEntry[] };
  if (!payload.entries) throw new Error("Missing LDAP search payload");
  return payload.entries;
}

curl -X POST "https://api.example.com/api/v1/integrations/<ENTITY_ID>/execute" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "search",
    "filter": "(mail=john.doe@example.com)",
    "scope": "sub",
    "attributes": ["cn", "mail", "memberOf"]
  }'

{
  "success": true,
  "entry_count": 1,
  "entries": [
    {
      "dn": "cn=John Doe,ou=Users,dc=example,dc=com",
      "cn": ["John Doe"],
      "mail": ["john.doe@example.com"]
    }
  ]
}

Authenticate directory users

The authenticate operation is useful when workflows must verify credentials before granting access or triggering sensitive actions. Keep authentication flows tightly scoped and avoid storing user passwords in process logs or persistent variables.

const baseUrl = "https://api.example.com/api/v1";
const tenantId = "<TENANT_ID>";
const apiKey = "<API_KEY>";

type AuthResult = {
  success: boolean;
  user_dn?: string;
  attributes?: Record<string, string[]>;
};

async function authenticateDirectoryUser(
  integrationId: string,
  username: string,
  password: string
): Promise<AuthResult> {
  const response = await fetch(
    `${baseUrl}/integrations/${encodeURIComponent(integrationId)}/execute`,
    {
      method: "POST",
      headers: {
        "X-API-Key": apiKey,
        "X-Tenant-ID": tenantId,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        operation: "authenticate",
        username,
        password,
        username_attribute: "userPrincipalName",
      }),
    }
  );

  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  return (await response.json()) as AuthResult;
}

Validate connectivity and operational safety

Run the connector test operation before go-live and after credential rotations or directory infrastructure changes. Most failures are caused by invalid bind credentials, DN scope mismatches, TLS/network issues, or insufficient directory permissions for write operations. Limiting filters, using least-privilege accounts, and logging execution identifiers improves both performance and troubleshooting quality.

curl -X POST "https://api.example.com/api/v1/integrations/<ENTITY_ID>/execute" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "test"
  }'

{
  "success": true,
  "data": {
    "status": "ok",
    "server_url": "ldaps://dc1.example.com:636",
    "base_dn": "dc=example,dc=com"
  }
}

Additional references

For deeper schema and attribute guidance, review the LDAP technical specifications, Microsoft Active Directory documentation, and LDAP filter syntax reference. Keeping filters and attributes aligned with directory standards helps maintain long-term integration reliability.