Active Directory Source Configuration

Key Takeaways

  • A user Search DN starts discovery in a specified directory container and the LDAP filter narrows the returned results.

  • Account search, group discovery and membership retrieval have distinct settings. Match each to the records required.

  • The VA-based Active Directory connector requires IQService for provisioning. Configure its supported Windows host, TLS and client authentication.

  • Cross-domain management requires documented domain trust and permissions. Test the exact account or group operation in an approved environment.

Last updated: November 2026

Identify the systems and operations

For SailPoint’s VA-based Microsoft Active Directory (AD) connector, record which forest, domain and organizational units (OUs) hold the accounts and groups. A forest groups domains. A distinguished name (DN) identifies a position in the directory. A search begins at the specified DN and uses the selected scope to determine how far to look below it. An optional Lightweight Directory Access Protocol (LDAP) filter further limits the objects returned.

Keep connector scope and connectivity distinct. Set up a VA cluster that can reach the required directory infrastructure. Configure the forest and the domain entries, including the domain DN, applicable service account, and the selected authentication and encryption settings. The account used for a read-only pilot needs the rights for its documented queries. Before enabling provisioning, verify the connector permissions needed for its specific writes. To manage users, groups and membership across different domains, SailPoint instructs engineers to ensure two-way trust and the necessary IQService service account permissions.

Integration decisionConfiguration to inspect
Which employees should be loaded?User Search DN, search scope and optional Iterate LDAP Search Filter
Which groups should be discovered?Group Search DN and optional group filter
Which group memberships should be read for a user?User Group Membership Search DN and filter settings
Which service performs provisioning for this connector?IQService Settings and operation-specific permissions
Why does the account test work but a write fail?Check the downstream IQService path, enablement and source permissions independently of the directory read

If an engineer configures a user search under an Employees OU, that prescribes where to look for user objects. Group memberships can refer to groups outside the user search container. SailPoint documents that omitting Group Membership Search DN brings memberships returned by the connector’s APIs. It does not automatically limit memberships to the account Search DN scope. For group discovery, leaving the explicit group search scope unset makes it follow the account scope. These are distinct defaults.

At domain level, SailPoint supports configuring more than one domain controller. If the first connection fails, the connector attempts to bind to the next configured controller. Leaving the server list empty uses serverless binding, which depends on correct DNS configuration. Choose which path to test based on the actual domain settings.

Exercise the Windows service path

IQService is installed on a supported Windows server with connectivity to the targets. The VA-based Active Directory connector requires it for provisioning and native rule execution, and for some read fields such as Terminal Services attributes. For this deployment configure Transport Layer Security (TLS) between VA and IQService and the required client authentication. Check that the configured hostname matches the certificate, the VA can reach the TLS port, and the relevant certificate chain is trusted. The VA’s outbound connection to SailPoint is a different path from its connections to the directory and IQService.

Suppose an organization can aggregate users by LDAP. Its attempt to create a test account fails with an IQService certificate-name error. Start with the configured IQService hostname, certificate name and TLS endpoint. Check the service and permissions for the provisioning operation when that connection is healthy. The successful LDAP read had demonstrated that one path worked. It provides no evidence that the IQService end of the request was valid.

Test the boundaries before rollout

An organization wants employee accounts within OU=Employees,DC=example,DC=org and membership visibility for approved groups in a separate OU. Configure and inspect user and group discovery scopes, and set membership retrieval according to the use case. In a sandbox or other approved controlled test, compare an expected account, an excluded account, an in-scope group and a membership outside the intended boundary. Check which inputs control each result. After an OU move, use a full aggregation following the connector guidance because delta aggregation does not support these moves.

If the organization later adopts a group Managed Service Account (gMSA) for this connector, SailPoint requires its documented IQService configuration and Strong authentication using the Simple Authentication and Security Layer (SASL). Verify those prerequisites instead of reusing the earlier service account configuration unchanged. The chosen deployment and supported feature matter more than a memorized list of directory ports.

See SailPoint’s forest, domain and search settings, IQService channel and client authentication, and delta aggregation limits.

Test Your Knowledge

A VA-based AD connector can aggregate ordinary user records, but account creation reports an IQService certificate hostname mismatch. What should the engineer check?

A

Whether delta aggregation is enabled on the user OU

B

The IQService endpoint’s configured hostname, TLS port and certificate identity

C

Whether AD group data has a display name

D

The profile priority of the HR source

Test Your Knowledge

The User Search DN is limited to the Employees OU. Group Membership Search DN is unset. What does that setting imply?

A

All group memberships are automatically scoped to the Employees OU

B

Membership collection is disabled

C

The connector only returns groups from its dedicated group search scope

D

Memberships returned by the connector APIs are not automatically restricted to the User Search DN scope

Sections you finish are checked off in the contents.