active-directory implementation guide

# Introduction

Microsoft Active Directory is the on-premises directory that holds your users, groups and organizational units. Connecting it to Tool Studio lets Moveworks plugins search directory objects and update entries such as group membership, through LDAP HTTP actions that the Moveworks On-Prem Agent carries into your network. This guide walks you through connecting Active Directory to Tool Studio and testing the connection.

Let's get started!

# Prerequisites

- The **Moveworks On-Prem Agent** installed inside your network, with line of sight to a domain controller on LDAP/LDAPS
- An Active Directory **service account** with read access to the OUs your plugins search, and write access to any attributes or groups they change
- Admin access to **Moveworks Setup**, to configure Built-In connectors

# Connect with the Built-In Active Directory Connector

## Step 1: Create the Built-In Active Directory connector

1. In **Moveworks Setup > Built-in Connectors**, add an **Active Directory** connector, or reuse the one you already have.
2. Fill in the connection details and the service account credentials the connector asks for, select the On-Prem Agent that routes the traffic, and save.
3. Confirm the agent shows **Healthy** under **Moveworks Setup > Core Platform > On-Premise Agents**.

## Step 2: Test with API Playground

Run one search before touching Tool Studio. In **Moveworks Setup > API Playground**, select the Active Directory connector; the base URL and authentication fill in automatically. Then call:

```bash
POST /ldap/v1/search
{
  "base_object": "OU=Users,DC=yourcompany,DC=com",
  "filter": "(&(objectClass=user)(mail=jane*))",
  "attributes": ["distinguishedName", "mail"]
}
```

`base_object` must name an OU beneath the domain. A domain-only value such as `DC=yourcompany,DC=com` fails because no valid search base can be resolved.

## Step 3: Connect Active Directory to Tool Studio

1. Make sure Built-In connectors are allowed in Tool Studio for your organization.
2. In Tool Studio, create an HTTP action, select **Inherit from existing connector**, and pick the Active Directory connector:
    - Base URL: `https://ldap-service.moveworks.int` (filled in automatically; it isn't publicly reachable, and Moveworks forwards the request through the On-Prem Agent)
    - Auth Config: inherited from the Built-In connector
3. Define the action to test the connector:

    ```bash
    POST /ldap/v1/search
    { "base_object": "OU=Users,DC=yourcompany,DC=com", "filter": "(objectClass=user)", "attributes": ["mail"], "size_limit": 5 }
    ```

    - Path: `/ldap/v1/search`
    - Method: `POST`
4. Click **Test** and look for an `entries` array in the response.

For dynamic filters, pass user input through `filter_args` rather than building the filter string yourself; the platform escapes the values, which prevents LDAP injection. To change entries, use `PUT /ldap/v1/modify` with `entry` plus at least one of `add`, `replace` or `delete`.

# Congratulations!

You've connected Active Directory to Tool Studio. Plugins can now look up users and managers, and update group membership in your directory from the Moveworks AI Assistant.