Integration Guide: Active Directory
Learn How to Connect the Active Directory Integration
Published Date: June 26, 2026 | Last Updated: October 19, 2026
Overview
The Active Directory integration connects Seasoft Identity to a Microsoft Active Directory domain controller using LDAPS. Seasoft Identity reaches the domain controller through the on-premises tunnel agent, which runs on a server in the organization’s network and makes outbound connections only. Directory traffic between Seasoft Identity and the domain controller is encrypted end to end with LDAPS. Because Active Directory is deployed and managed as part of the organization’s infrastructure, the values required are specific to the organization’s environment. This guide explains what each field expects — the IT Administrator or domain owner supplies the environment-specific values.
Active Directory or Microsoft Entra ID? If the organization uses Microsoft Entra ID (Azure AD), use the Microsoft Entra ID integration instead. In a hybrid environment with both on-premises AD and Azure AD, only 1 integration is needed — not both. Rather than connecting both, Seasoft Solutions recommends running delta syncs to keep the on-premises and cloud directories aligned. Microsoft Entra ID is recommended for most organizations. The Active Directory integration is recommended for organizations running purely on-premises environments with no Azure AD presence.
On-premises tunnel agent required: The Active Directory integration requires the on-premises tunnel agent. Before starting, confirm the agent host meets the host, network, and firewall requirements in On-premises tunnel agent requirements.
Before connecting
The Administrator completing this setup needs access to the Active Directory domain, a server that meets the tunnel agent requirements, and the following Active Directory details.
Active Directory requirements
| Item | Requirement |
|---|---|
| LDAPS | Enabled on the domain controller on port 636. Required for tunnel connections. |
| Domain controller hostname | The fully qualified domain name of the domain controller (for example, dc01.corp.example.com). The name must appear as a Subject Alternative Name on the domain controller’s LDAPS certificate. Use the hostname, not the IP address. |
| CA certificate | The certificate of the CA that issued the domain controller’s LDAPS certificate, as a PEM file. Required when the issuing CA is internal, such as Active Directory Certificate Services. |
| Service account | A Bind DN and password. Discovery requires read access to users and groups. Provisioning (creating, updating, and disabling Users and managing group membership) requires delegated write access on the OUs Seasoft Identity manages. |
| Base DN | The starting point for directory operations (for example, DC=corp,DC=example,DC=com). Separate base DNs for users and groups are optional. |
Network requirements
In addition to the tunnel agent network requirements, the agent host must reach the domain controller.
| Path | Requirement |
|---|---|
| Agent host to domain controller | TCP 636 (LDAPS). |
| Name resolution | The agent host resolves the domain controller’s hostname through DNS. If DNS resolution is not available, add a hosts file entry on the agent host. |
Step 1: Install the tunnel agent
Skip this step if a tunnel agent that can reach the domain controller is already connected.
- Navigate to Integrations › Tunnel Agents.
- Create a tunnel agent. Enter a Display name that identifies its location or the server it runs on (for example,
chi-datacenter-01), and select Create agent. - Copy the setup commands. The dialog shows a provisioning token that appears only once and expires after 15 minutes. The commands already include the token, so keep the dialog open until every command has run. If the token expires, generate a new one.
- Run each command block on the agent host, in an elevated PowerShell (Windows Server) or a terminal (Linux).
Confirmation: The agent shows as connected on the Tunnel Agents page. Health status can take up to 10 minutes to appear. If the agent does not connect, verify the agent host meets the tunnel agent requirements, including the proxy and TLS inspection exemptions.
Step 2: Add the Active Directory integration
- Navigate to Integrations › Connections.
- Add the Active Directory integration.
- Turn on the Tunnel toggle at the top of the dialog, and select the agent if prompted.
- Enter the connection settings described below.
- Allow the domain controller on the agent host. After the Host is entered, the dialog shows a command at the bottom. Run it on the agent host in an elevated PowerShell or a terminal before continuing.
- Select Connect. Seasoft Identity verifies the connection through the tunnel.
Note: Test Connection is not yet available for tunnel connections. Seasoft Identity verifies the connection when Connect is selected.
Connection settings
| Field | Description |
|---|---|
| Tunnel | Routes the connection through the on-premises tunnel agent. Turn this toggle on, at the top of the dialog. |
| Agent | The tunnel agent that reaches the domain controller. Select it if prompted. |
| Host | The fully qualified hostname of the domain controller. It must match a Subject Alternative Name on the domain controller’s LDAPS certificate. |
| Port | The LDAPS port. Use 636. |
| Use TLS (LDAPS) | Enables a secure LDAPS connection. Enabled by default and required for tunnel connections. |
| CA Certificate (PEM) | A PEM-encoded CA certificate for validating the domain controller’s TLS certificate. Required if the domain controller uses a self-signed or internal CA certificate. |
| Bind DN | The Distinguished Name of the service account used to authenticate to Active Directory (for example, CN=ServiceAccount,OU=ServiceAccounts,DC=example,DC=com). |
| Bind Password | The password for the Bind DN service account. |
| Base DN | The base Distinguished Name used as the starting point for all directory operations (for example, DC=example,DC=com). |
Advanced options
Select Advanced Options to expand additional configuration fields. These fields are optional and fall back to the Base DN if left empty. Default values are pre-filled for standard Active Directory environments.
| Field | Description |
|---|---|
| User Base DN | Relative DN scoping user searches (for example, OU=Users). Uses Base DN if empty. |
| Group Base DN | Relative DN scoping group searches (for example, OU=Groups). Uses Base DN if empty. |
| User Search Filter | LDAP filter for user searches. Default is (&(objectClass=user)(objectCategory=person)). |
| Group Search Filter | LDAP filter for group searches. Default is (objectClass=group). |
| User Object Classes | Object classes used for user records. Default is top, person, organizationalPerson, user. |
| Group Object Classes | Object classes used for group records. Default is top, group. |
Verify the connection
After the initial sync completes, confirm the following on the Integrations page:
- The Active Directory integration displays a status of
Active - A sync timestamp is present and reflects the completed sync
- User records on the Users page reflect the users and groups imported from Active Directory
Related articles
- On-premises tunnel agent requirements — prepare the server and network for the tunnel agent
- Configuring Integrations — manage sync schedules, drift detection, and integration settings
- Understanding Errors — resolve integration errors and authorization failures