Skip to content

Active Directory Troubleshooting and Validation

Steps to validate a successful integration and what to do when the test connection fails. For setup information, refer to Active Directory Onboarding Guide.

Validation Steps After Connection

  1. Verify integration in SailPoint Entro Console

    Go to Management > Accounts & Integrations > Active Directory.

  2. Confirm account status

    Verify account status shows Verified.

  3. Check findings and inventory

    Confirm findings appear in NHI Inventory as Identity Type: AD Local Service Account.

  4. Check sync timestamp

    Check last sync timestamp on the integration card.

What the Connection Test Checks

Check Required? If it fails
LDAPS connection and service-account sign-in Yes Refer to Connection and DNS, Certificate, and Sign-in (bind).
Read domains, users, computers, and groups Yes Refer ti Partial or Missing Objects.
Root CA is in date Yes Export a current root CA and paste it into the account.
Global Catalog Only for forests with more than one domain Refer to Global Catalog.
Read ACLs No Objects are collected without their ACLs, so there is no attack-path data. Refer to Partial or Missing Objects.

Data Visibility Checks

Compare SailPoint Entro's counts with AD's. These commands use the same LDAP filters as SailPoint Entro, per domain:

(Get-ADObject -LDAPFilter '(&(objectCategory=person)(objectClass=user))').Count # users
(Get-ADObject -LDAPFilter '(objectClass=group)').Count # groups
(Get-ADObject -LDAPFilter '(objectClass=computer)').Count # computers

  • Managed service accounts (MSA and gMSA) are computer objects in AD, so they are counted with computers.

  • Search SailPoint Entro's inventory for a known user, and check attributes such as userPrincipalName and group membership.

Test from the Connector

Run tests from where the connector runs. For a containerized connector, run them inside the container, whose DNS can differ from the host's. The Active Directory Onboarding Guide has checks for a Linux host, inside a Docker container, and on a Windows host.

To test the service account's sign-in from a Linux host (it prompts for the password):

LDAPTLS_CACERT=root-ca.pem ldapsearch -x -H ldaps://dc01.corp.example.com:636 \
  -D "svc_entro@corp.example.com" -W -b "" -s base defaultNamingContext isGlobalCatalogReady

To check the certificate the DC serves (expect Verify return code: 0 (ok)):

openssl s_client -connect dc01.corp.example.com:636 -servername dc01.corp.example.com \
  -verify_hostname dc01.corp.example.com -CAfile root-ca.pem </dev/null | grep -E 'subject=|issuer=|Verify return code'

Note

Do not test with ldap:// on port 389 without StartTLS: it sends the password in clear text, and the connector never connects that way. Use -W to be prompted for the password, rather than putting it on the command line.

Common Issues and Resolutions

The connection test provides a message when the connection has failed.

Connection and DNS

Message contains Cause Fix
does not resolve from the connector The DNS server the connector asked doesn't know the DC's name. The error names that server. For example, lookup dc01.corp.example.com on 172.20.0.10:53. Open DNS where the Connector Runs, below this table.
could not be resolved, since the DNS server did not answer The connector's DNS server is unreachable. Allow UDP and TCP 53 to your DNS servers.
timed out, so a firewall or route is dropping the traffic A firewall, NSG, or route drops the traffic. Allow TCP 636 (and 3269) from the connector to the DC.
refused the connection, so nothing is listening on this port Nothing listens on 636, usually because the DC has no LDAPS certificate. Refer to Certificate.
the connector has no route to the DC No network path. Check routing, VPN, or VNet peering between the connector and the DC.

DNS where the Connector Runs

The connector uses the DNS of where it runs. In Docker or Kubernetes, that's the container's or the cluster's, not the host's. Check it inside the container with cat /etc/resolv.conf.

Quickest fix: enter the DC's IP in the account's Domain Controller (DC) field and keep its FQDN in DC FQDN. The connector then needs no DNS lookup for the DC.

Docker Compose: add dns: (your AD DNS server) or extra_hosts: ("dc01.corp.example.com:<DC IP>") to the connector's service, then run docker compose up -d --force-recreate. docker compose restart does not apply compose changes. Confirm them with docker inspect -f "{{.HostConfig.Dns}} {{.HostConfig.ExtraHosts}}" <container>.

Docker on Windows: do not use the address of the vEthernet (WSL) adapter (usually 172.x.x.1) as the DC's IP. It's the Windows host's virtual adapter, and it changes on reboot. Use the DC's real IP, from Resolve-DnsName dc01.corp.example.com or ipconfig on the DC.

The error names a DNS server your connector doesn't use? Then the test ran on a different connector. Check that the account's Worker Group is the connector that can reach the DC.

Azure: Azure's default DNS doesn't know your AD zone. Point the VNet's DNS at your DCs, or add a conditional forwarder for your AD domain.

docker commands return 500 Internal Server Error: Docker Desktop's engine isn't answering. Quit Docker Desktop, run wsl --shutdown, and start it again.

Certificate

Message contains Cause Fix
the DC closed the connection during the TLS handshake No LDAPS certificate enrolled on the DC, TLS 1.2 disabled, or plain LDAP on the port. Enroll an LDAPS certificate on the DC (AD CS Kerberos Authentication or Domain Controller Authentication template), and enable TLS 1.2.
accepted the connection but did not complete the TLS handshake in time Something on the path holds the connection open without TLS, such as a proxy or an inspecting firewall. Allow TCP 636 to the DC directly, with no TLS inspection.
the port does not speak TLS The port serves plain LDAP. Use 636 for LDAPS.
the certificate was not issued by the account's root CA The pasted Root CA isn't the one that issued the DC's certificate. Export the root of the DC's chain (refer to Export the Root CA). A bundle with intermediates is accepted.
the certificate does not name The account's DC FQDN isn't in the certificate's Subject Alternative Name. Set DC FQDN to a name on the certificate, or reissue the certificate.
signed with an algorithm the connector refuses, such as SHA-1 SHA-1 certificate. Reissue it from a SHA-256 template.
the certificate is not valid / the certificate failed verification The DC's certificate is expired, not yet valid, or not usable for server authentication. Renew the DC's certificate.
root CA ... expired / is not valid until / Invalid certificate date range The pasted Root CA is out of date. Paste a current root CA.
rootCA is required The Root CA (PEM) field is empty. Paste the root CA; it is required even though the form doesn't mark it.

Sign-in (bind)

Message contains Cause Fix
refused the bind: ... AD rejected the service account. The message says why. Refer to the AD error codes below.
accepted the connection but did not answer the bind The DC stopped answering after TLS was set up. Retry. If it persists, check the DC's health and any device between the connector and the DC.

AD Error Codes in Bind Failures

Code Meaning Fix
525 User not found Check the UPN in Username.
52e Wrong username or password Re-enter the password in SailPoint Entro.
530 Logon hours don't allow this time Allow all logon hours for the account.
531 "Log On To" doesn't allow the connector Set "Log On To" to all computers.
532 Password expired Reset it, then update SailPoint Entro.
533 Account disabled Enable the account.
701 Account expired Set the account to never expire.
773 User must change password at next logon Set a password, and clear the flag.
775 Account locked out Unlock it. A wrong password saved in SailPoint Entro locks it again, so fix that first.

Global Catalog

Message contains Cause Fix
read only through a Global Catalog, and none answered A multi-domain forest, and no Global Catalog reachable. Only a Global Catalog holds the other domains' users. Open TCP 3269 (or 3268) from the connector to the DC, or configure a DC that is a Global Catalog.
did not answer as a Global Catalog (warning) The configured DC's Global Catalog ports didn't answer. Fine for a single-domain forest. Otherwise, as above.
did not answer StartTLS in time Port 3268 answered but StartTLS didn't complete. Open 3269 (LDAPS) instead, or allow StartTLS through any inspecting device.

To check which DCs are Global Catalogs:

Get-ADDomainController -Filter * | Select-Object Name, Site, IsGlobalCatalog

Partial or Missing Objects

Symptom Cause Fix
Test says cannot read nTSecurityDescriptor, or there is no attack-path data The service account lacks Read permissions on the domain. Grant Read on the domain root, This object and all descendant objects.
Some OUs, users, or groups are missing The default read access was tightened on those objects. Grant Read on the domain root, as above. For privileged accounts, also grant Read on CN=AdminSDHolder,CN=System,<domain>.
Users of child domains are missing No Global Catalog was reachable. Refer to Global Catalog.
Users of another forest are missing Other forests are not collected through trusts. Onboard that forest as its own account.

Large Forests and Long Collections

  • Collection uses paged LDAP searches, so AD's per-query size limit (MaxPageSize, 1000 by default) doesn't truncate results. Large groups are read in full, too.

  • Very large forests take longer to collect. Give the Worker Group enough resources.

  • To limit collection to part of the directory (a base DN or a user filter), contact SailPoint Entro Support.

Clock and Time Sync

SailPoint Entro doesn't use Kerberos, so clock drift doesn't break the sign-in. A connector clock that is far off can still make a valid certificate look expired or not yet valid. Keep the connector host in sync with NTP.

Advanced Diagnostics

  • Enable debug logs on the Worker Group and collect connector logs.

  • Capture a packet trace (tcpdump port 636) on the connector host to confirm the TLS handshake reaches the DC.

  • Export the SailPoint Entro connector log bundle and attach it to your support ticket.

Support

If validation continues to fail, contact SailPoint Entro Support:

  • Slack or Teams channel for your customer success manager

  • support@entro.security

Provide connector logs, the connector log bundle, and the exact error from the connection test when contacting support, to speed up troubleshooting.

Security & Compliance Notes

  • Keep the service account read-only: a member of Domain Users only.

  • The connector uses LDAPS or StartTLS with TLS 1.2+. Never test the account with an unencrypted bind.