> For the complete documentation index, see [llms.txt](https://docs.harmony.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.harmony.io/integrations/identity-provider/active-directory.md).

# Active Directory

Harmony connects to your on-premises Microsoft Active Directory (AD) to automate user lifecycle management and group membership - without exposing your internal network. Once connected, you can create users, disable users, manage group membership, and trigger access changes directly from your AI agent workflows.

***

#### What the Active Directory integration enables

| Capability                | Description                                                                                                              |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Group Management          | Add and remove users from Active Directory groups via Harmony workflows                                                  |
| User Lifecycle Automation | Create and disable AD user accounts, and trigger group changes automatically on onboarding, offboarding, or role changes |
| Access Provisioning       | Grant or revoke access to connected applications automatically when AD group membership changes                          |
| Secure Connectivity       | Communicate with your on-premises AD over an encrypted tunnel with no inbound firewall rules required                    |

***

#### How It Works

Harmony connects to your on-premises Active Directory over **LDAPS (port 636)** through a secure **Cloudflare Tunnel**. The Cloudflare tunnel agent (`cloudflared`) is installed as a Windows service on a member server that has access to the Domain Controller. It establishes an **outbound-only** connection to Cloudflare's edge, so no inbound firewall rules are needed. Harmony then communicates with your AD through this tunnel.

***

#### Prerequisites

Before setting up the integration, ensure you have:

1. A **Windows Server** (member server) with network access to your Domain Controller
2. **Active Directory Users and Computers** access to create a service account and delegate permissions
3. **Harmony admin access** to configure the integration

{% hint style="info" %}
Outbound traffic on port **7844** (UDP + TCP) must be allowed from the Windows Server where `cloudflared` will be installed. TCP only is sufficient if UDP is blocked. No inbound ports are required.
{% endhint %}

***

#### Step 1: Create a Service Account

1. Open **Active Directory Users and Computers**
2. Create a new user for the service account (e.g., `svc-harmony`)
3. Uncheck **User must change password at next logon**
4. Optionally check **Password never expires**

***

#### Step 2: Delegate Permissions

Harmony requires permission to modify group membership on the OUs that contain the groups it will manage.

1. Open **Active Directory Users and Computers**
2. Right-click the target OU and select **Delegate Control**
3. Add the service account and grant **Modify group membership**

{% hint style="info" %}
Delegation is inherited by child OUs. If your users and groups span multiple OUs, delegate on the highest common parent OU to cover all of them with a single delegation.
{% endhint %}

***

#### Step 3: Configure the Integration in Harmony

1. Log into your Harmony dashboard
2. Navigate to **Settings > Integrations**
3. Find **Active Directory** under **Identity Provider**
4. Fill in the following fields:

| Field                 | Description                                                                                               | Required |
| --------------------- | --------------------------------------------------------------------------------------------------------- | -------- |
| **Domain Controller** | IP or internal hostname of the DC (e.g., `10.0.1.50` or `dc01.corp.local`)                                | Yes      |
| **Service Account**   | UPN of the LDAP service account (e.g., `svc-harmony@corp.local`)                                          | Yes      |
| **Password**          | Service account password                                                                                  | Yes      |
| **Base DN**           | Root of LDAP searches (e.g., `DC=corp,DC=local`). Auto-derived from the service account UPN if left blank | No       |

{% hint style="info" %}
The service account UPN domain may differ from the Base DN. For example, `svc@test.com` (UPN with alternate suffix) paired with `DC=trad,DC=local` (actual AD domain) is a valid configuration. When in doubt, set the Base DN explicitly.
{% endhint %}

5. Save the integration. Harmony will generate two PowerShell commands for the next step.

***

#### Step 4: Install the Cloudflare Tunnel Agent

On the Windows Server where `cloudflared` will run:

1. Run the **Step 1** PowerShell command provided by Harmony to download and install Cloudflare
2. Run the **Step 2** install command (this contains the tunnel token unique to your integration)
3. Click **Test connection** in the Harmony UI to verify the tunnel is working

***

#### Workflow Blocks

Once your Active Directory integration is connected, you can use the following blocks in your AI agent workflows to automate user lifecycle and access management.

**Create AD User**

The **Create AD User** block provisions a new user account in your on-premises Active Directory directly from a workflow. The create user form is organized into clear sections so you have full control over the user record at creation time.

**Mandatory fields:**

| Field            | Description                               |
| ---------------- | ----------------------------------------- |
| Description      | A description for the user account        |
| Telephone Number | The user's office telephone number        |
| Email Address    | The user's email address                  |
| State            | The user's state or province              |
| Country          | The user's country                        |
| Mobile Number    | The user's mobile phone number            |
| Job Title        | The user's job title                      |
| Department       | The department the user belongs to        |
| Company          | The company name associated with the user |
| Manager          | The user's manager                        |

**Optional Unix/POSIX fields:**

For organizations that require Linux/Unix account attributes alongside AD accounts, you can populate Unix/POSIX fields at creation time.

**Extension attributes:**

Additional extension attributes are available to store supplementary information on the user object.

**Disable AD User**

The **Disable AD User** block deactivates an existing Active Directory user account from within a workflow. Use this block to automate offboarding or suspend access immediately when a role or employment status changes.

**Add and Remove Users from Groups**

You can add and remove users from Active Directory groups as part of any workflow. When group membership changes, connected applications can automatically reflect those changes - granting or revoking access accordingly. All membership changes are logged for visibility into user management actions.

{% hint style="info" %}
You can use AD group membership as a trigger or condition in your workflows to automate app access provisioning at scale, keeping your team's permissions in sync with your directory structure.
{% endhint %}

***

#### Useful Commands

Run these on the Domain Controller to look up values needed during setup:

```powershell
# Get the DC hostname
$env:LOGONSERVER

# Get the Base DN
(Get-ADDomain).DistinguishedName

# Verify the service account UPN
Get-ADUser -Identity <sAMAccountName> -Properties userPrincipalName | Select-Object userPrincipalName
```

Run this on the member server (where `cloudflared` is installed) to verify LDAPS connectivity:

```powershell
# Test LDAPS port
Test-NetConnection -ComputerName dc01.corp.local -Port 636
```

***

#### Firewall Requirements

| Port | Protocol  | Direction | Purpose                                             |
| ---- | --------- | --------- | --------------------------------------------------- |
| 7844 | UDP + TCP | Outbound  | Cloudflare tunnel (QUIC preferred, HTTP/2 fallback) |

No inbound ports are required.

***

Need help? Contact [**support@harmony.io**](mailto:support@harmony.io) for assistance with your Active Directory integration.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.harmony.io/integrations/identity-provider/active-directory.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.