Active Directory

Connect Harmony with your on-premises Active Directory to manage group membership, reset passwords, and automate user lifecycle workflows

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, reset passwords, unlock accounts, 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
Password Reset	Reset passwords and unlock accounts in Active Directory, including for Microsoft Entra users synced from your on-premises directory
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

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.

---

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

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.

Password Reset Permissions

Only needed if Harmony resets passwords in Active Directory: when Reset passwords in Active Directory is turned on for a Microsoft Entra connection in the Password Reset agent, or when a workflow uses the Reset AD Password or Unlock AD User blocks.

On the OUs that contain the users, delegate to the service account:

1. Right-click the OU and select Delegate Control, then add the service account
2. Select the common task Reset user passwords and force password change at next logon. This grants Reset password and Read/Write pwdLastSet
3. Run Delegate Control again, choose Create a custom task to delegate, then Only the following objects in the folder > User objects
4. Under Property-specific, grant Read lockoutTime and Write lockoutTime, so Harmony can unlock a locked-out account

Without these permissions, a reset in Active Directory fails with "Insufficient access rights" and the request is handed to your IT team.

---

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., [e-mail])	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

The service account UPN domain may differ from the Base DN. For example, [e-mail] (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.

1. 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.

Reset AD Password

The Reset AD Password block sets a temporary password on an Active Directory account and returns it to the workflow so it can be delivered to the employee. It unlocks the account first if it is locked out, and by default requires the employee to choose their own password at their next Windows sign-in. Needs the password reset permissions.

For users synced to Microsoft Entra, a password the employee must change is not synced by default: Microsoft Entra receives the password the employee sets at their next Active Directory sign-in, and keeps accepting their previous password until then. With the block's must-change-at-next-logon option turned off, the new password syncs as it is. See Users synced from on-premises Active Directory.

Unlock AD User

The Unlock AD User block clears an account lockout without changing the password. Needs the lockoutTime permission from password reset permissions.

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.

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.

---

Useful Commands

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

# 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:

# 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 [e-mail] for assistance with your Active Directory integration.