Build an Active Directory LDAP Browser

This guide describes an Extend source connector that reads directory entries over LDAP, flattens attributes, and produces a CSV or JSON output file for downstream SchemAlign nodes.

The connector is a source-style Extend app. It is not a built-in node and should be created through Admin > Extend.

Connector summary

Setting	Value
Connector type	Source
Recommended node key	active_directory_ldap_browser
Entrypoint	connector:run
Python version	3.14.4
Dependencies	ldap3==2.9.1, requests==2.33.0
Credential model	account_id using a basic-auth account
Output formats	CSV or JSON
Default output filename	active_directory_export.csv

Required account

Create a SchemAlign account using a basic-auth style credential. The account should contain the LDAP bind username and password.

The connector schema should expose only the account reference:

{
  "account_id": {
    "type": "string",
    "title": "Account",
    "description": "SchemAlign basic-auth account UUID used for the LDAP bind username and password."
  }
}

At runtime, SchemAlign resolves the account server-side. Connector code should read the injected credentials from input_payload.credentials.

Configuration fields

Field	Description
Account	SchemAlign account reference used to resolve the LDAP bind username and password at runtime.
Server URI / host	Domain controller host, FQDN, or LDAP URI, such as dc01.example.com or ldaps://dc01.example.com.
Port	LDAP port. The default is 636.
Use SSL	Connect with LDAPS when enabled.
Search base DN	LDAP base DN. Leave blank to use the server default naming context when available.
Search filter	LDAP filter. The default is (objectClass=*).
Attributes mode	all requests all attributes, common requests a smaller common set, and custom uses the explicit Attributes list.
Attributes	Explicit LDAP attributes to request when using custom mode.
Include operational attributes	Requests LDAP operational attributes in addition to standard attributes.
Exclude DN contains	Skips entries whose distinguished name contains any configured fragment.
LDAP page size	Page size for paged LDAP results. The default is 1000.
Size limit	Client-side size limit. Use 0 for no client-side limit.
Output filename	File name for the generated output.
Output format	csv or json.
Multi-value separator	Separator used when flattening multi-valued LDAP attributes into a single CSV cell.
Also publish artifact copy	Optional durable copy in the file plane. Downstream connected nodes should normally consume the stream handoff directly.
Keep artifact history	Keeps artifact history when durable artifact publishing is enabled.

Suggested configuration schema

Use this schema as the starting point for the connector version settings.

{
  "type": "object",
  "additionalProperties": true,
  "properties": {
    "account_id": {
      "type": "string",
      "title": "Account",
      "description": "SchemAlign basic-auth account UUID used for the LDAP bind username and password."
    },
    "server_uri": {
      "type": "string",
      "title": "Server URI / host",
      "description": "Domain controller host, FQDN, or ldap(s) URI. Example: dc01.example.com or ldaps://dc01.example.com"
    },
    "port": {
      "type": "integer",
      "title": "Port",
      "default": 636
    },
    "use_ssl": {
      "type": "boolean",
      "title": "Use SSL",
      "default": true
    },
    "search_base": {
      "type": "string",
      "title": "Search base DN",
      "default": "",
      "description": "LDAP base DN. Leave blank to use the server default naming context when available."
    },
    "search_filter": {
      "type": "string",
      "title": "Search filter",
      "default": "(objectClass=*)",
      "description": "LDAP filter. Default returns all directory entries under the search base."
    },
    "attributes_mode": {
      "type": "string",
      "title": "Attributes mode",
      "enum": ["all", "common", "custom"],
      "default": "all",
      "description": "all = all directory attributes. common = smaller subset. custom = use the explicit Attributes list below."
    },
    "attributes": {
      "type": "array",
      "title": "Attributes",
      "items": {"type": "string"},
      "default": [],
      "description": "Explicit LDAP attributes to request. Used when attributes_mode=custom. Also respected when supplied without attributes_mode."
    },
    "include_operational_attributes": {
      "type": "boolean",
      "title": "Include operational attributes",
      "default": false
    },
    "exclude_dn_contains": {
      "type": "array",
      "title": "Exclude DN contains",
      "items": {"type": "string"},
      "default": []
    },
    "page_size": {
      "type": "integer",
      "title": "LDAP page size",
      "default": 1000
    },
    "size_limit": {
      "type": "integer",
      "title": "Size limit",
      "default": 0
    },
    "filename": {
      "type": "string",
      "title": "Output filename (optional)",
      "default": "active_directory_export.csv"
    },
    "output_format": {
      "type": "string",
      "title": "Output format",
      "enum": ["csv", "json"],
      "default": "csv"
    },
    "multivalue_separator": {
      "type": "string",
      "title": "Multi-value separator",
      "default": " | "
    },
    "publish_artifact": {
      "type": "boolean",
      "title": "Also publish artifact copy",
      "default": false
    },
    "publish_history": {
      "type": "boolean",
      "title": "Keep artifact history",
      "default": true
    }
  },
  "x-ui": {
    "tabs": [
      {
        "id": "connection",
        "title": "Connection",
        "columns": 2,
        "fields": ["account_id", "server_uri", "port", "use_ssl", "search_base", "search_filter"]
      },
      {
        "id": "query",
        "title": "Query",
        "columns": 2,
        "fields": ["attributes_mode", "attributes", "include_operational_attributes", "exclude_dn_contains", "page_size", "size_limit"]
      },
      {
        "id": "output",
        "title": "Output",
        "columns": 2,
        "fields": ["filename", "output_format", "multivalue_separator", "publish_artifact", "publish_history"]
      }
    ]
  }
}

Test metadata

Use mock mode for safe draft testing.

{
  "mode": "mock",
  "output_format": "csv",
  "publish_artifact": false,
  "publish_history": false
}

Source code expectations

The connector source should:

• import ldap3 inside live mode so mock mode can run without connecting to a directory
• support mode: mock for safe testing
• read credentials.username and credentials.password from runtime-enriched input payload
• resolve blank search_base from the server default naming context when available
• use paged LDAP search
• flatten multi-valued attributes into CSV cells with the configured separator
• support JSON output for structured review
• sanitize unsafe filename characters
• write output only under output_dir
• return row counts, column counts, skipped DN count, output filename, MIME type, and output path

Common attribute modes

Mode	Behavior
all	Requests all standard attributes.
common	Requests a curated common set such as name, mail, account name, department, title, manager, timestamps, and group membership.
custom	Requests the exact attributes listed in the Attributes field.

Build steps

1. Create a connector draft with node key active_directory_ldap_browser.
2. Set connector type to Source.
3. Set entrypoint to connector:run.
4. Set Python version to 3.14.4.
5. Add dependencies:

ldap3==2.9.1
requests==2.33.0

1. Paste the configuration schema into the version settings.
2. Paste the safe test metadata into the version settings.
3. Add or replace connector.py with the LDAP browser connector source.
4. Validate the draft.
5. Build the dependency environment.
6. Run mock test mode first.
7. Run live test mode only with an approved account and safe search scope.
8. Publish the version.
9. Install the published version to an organization.
10. Approve requested capabilities, if any.
11. Add the installed connector in Workspace and connect it to downstream nodes.

Safe live-testing recommendations

Start with a narrow search base and filter. Avoid a full directory export until the connector has passed with a small scope.

Examples:

search_base=OU=Users,DC=example,DC=com
search_filter=(objectClass=person)
attributes_mode=common
size_limit=100

Downstream usage

The connector writes a file under the connector output directory. SchemAlign can use the selected output file as the stream handoff to downstream connected nodes. Durable artifact publishing should be used only when a retained file copy is needed for review or later download.

AI assistance

Before asking an AI assistant to generate or modify the connector source, share the AI Connector Contract.