title: Connection Troubleshooting Guide category: Connections tags: troubleshooting, connection, ldap, network, errors, diagnostics priority: Normal

Connection Troubleshooting Guide

When a connection to Active Directory, Entra ID, or another directory source fails, this guide helps you diagnose the root cause and apply the correct fix. Work through the quick diagnostic checklist first, then find your specific error in the reference below.

Quick Diagnostic Checklist

Before diving into specific errors, verify these fundamentals:

If all six checks pass and the connection still fails, look at the specific error message in the sections below.

Error Reference: Active Directory / LDAP

"The server is not operational"

Cause: The domain controller is unreachable from the IdentityCenter server.

Possible reasons:

• The domain controller is powered off or has crashed
• A firewall is blocking LDAP traffic (port 389 or 636)
• DNS is returning the wrong IP address for the DC hostname
• The DC hostname is misspelled in the connection settings

Fix:

1. Ping the domain controller from the IdentityCenter server
2. Test port connectivity: Test-NetConnection dc01.corp.local -Port 389
3. Verify DNS resolution: nslookup dc01.corp.local
4. If using a hostname, try the IP address directly to rule out DNS issues
5. Check Windows Firewall on the DC for blocked inbound LDAP rules

"Invalid credentials"

Cause: The username or password in the connection settings is incorrect.

Possible reasons:

• Password was changed but not updated in IdentityCenter
• Service account is locked out due to failed login attempts
• Username format is wrong (e.g., using jsmith instead of CORP\jsmith or jsmith@corp.local)

Fix:

1. Verify the password by logging into a domain-joined computer with the service account
2. Check for account lockout in Active Directory Users and Computers
3. Try different username formats:

"Unwilling to perform"

Cause: The directory server is refusing the requested operation.

Possible reasons:

• The server requires SSL/TLS but the connection is using plain LDAP
• The service account does not have permission for the requested operation
• LDAP signing or channel binding is required by Group Policy

Fix:

1. If your domain requires LDAP signing (common after security hardening), switch to LDAPS (port 636) or enable LDAP signing in the connection settings
2. Verify the service account has read permissions on the target OUs
3. Check Group Policy: Computer Configuration > Policies > Windows Settings > Security Settings > Local Policies > Security Options > Domain controller: LDAP server signing requirements

"A referral was returned from the server"

Cause: The LDAP query is reaching a domain controller that does not hold the requested data and is referring the client to another server.

Possible reasons:

• The Base DN in the connection settings points to a different domain than the DC you are connecting to
• You are querying a child domain's DC for objects in the parent domain
• The connection is targeting a domain controller, but needs the Global Catalog

Fix:

1. Verify the Base DN matches the domain of the target DC
2. If you need to query across domains in a forest, use the Global Catalog port (3268 or 3269)
3. Set referral handling to Follow in the connection's advanced settings

"Size limit exceeded"

Cause: The LDAP query returned more results than the server allows in a single response.

Details: Active Directory has a default MaxPageSize of 1000 objects per page. IdentityCenter uses paged LDAP searches automatically, so this error is rare. If you see it:

Fix:

1. Ensure you are using the latest version of IdentityCenter (paged search is automatic)
2. If using a custom LDAP client for testing, enable paging
3. Check if the AD administrator has reduced the MaxPageSize below 1000

"The LDAP server is unavailable"

Cause: The connection to the LDAP server was interrupted or could not be established.

Possible reasons:

• The domain controller service (NTDS) has stopped
• A network device (firewall, load balancer) is dropping the connection
• The LDAP port is not listening on the target server
• DNS is returning a stale or incorrect IP

Fix:

1. Verify the DC is running: check nltest /dsgetdc:corp.local from a domain-joined machine
2. Test from the IdentityCenter server: Test-NetConnection dc01.corp.local -Port 389
3. Check for network devices that might be terminating idle connections (increase idle timeout or use connection keep-alive)

"The supplied credential is invalid" (LDAPS)

Cause: LDAPS connection failed due to a certificate issue, but the error message is misleading.

Fix: See the LDAPS Certificate Troubleshooting section below.

Error Reference: Entra ID

"AADSTS7000215: Invalid client secret"

Cause: The client secret provided does not match or has expired.

Fix:

1. Check the secret expiration date in Azure Portal > App registrations > Certificates & secrets
2. If expired, create a new client secret and update the connection in IdentityCenter
3. Ensure you copied the Value column (not the Secret ID)

"AADSTS700016: Application not found"

Cause: The Client ID does not match any app registration in the specified tenant.

Fix:

1. Verify the Client ID matches the Application (client) ID in Azure Portal
2. Confirm the Tenant ID is correct
3. Ensure the app registration has not been deleted

"Insufficient privileges to complete the operation"

Cause: The app registration does not have the required Graph API permissions, or admin consent has not been granted.

Fix:

1. Go to Azure Portal > App registrations > your app > API permissions
2. Verify that User.Read.All, Group.Read.All, and Directory.Read.All are listed
3. Ensure the Status column shows "Granted for [tenant]" (green check)
4. If not, click Grant admin consent

LDAPS Certificate Troubleshooting

If you are using LDAPS (port 636), certificate issues are a common source of failures.

Common Certificate Problems

Verifying the DC Certificate

From the IdentityCenter server (PowerShell):

$tcpClient = New-Object System.Net.Sockets.TcpClient("dc01.corp.local", 636)
$sslStream = New-Object System.Net.Security.SslStream($tcpClient.GetStream(), $false)
$sslStream.AuthenticateAsClient("dc01.corp.local")
$cert = $sslStream.RemoteCertificate
Write-Host "Subject: $($cert.Subject)"
Write-Host "Issuer: $($cert.Issuer)"
Write-Host "Expires: $($cert.GetExpirationDateString())"
$sslStream.Close()
$tcpClient.Close()

Installing a Trusted Root CA

If the domain controller's certificate is issued by an internal CA that the IdentityCenter server does not trust:

1. Export the root CA certificate from your certificate authority
2. On the IdentityCenter server, open certlm.msc (Local Computer certificates)
3. Navigate to Trusted Root Certification Authorities > Certificates
4. Right-click > All Tasks > Import and select the CA certificate
5. Restart the IdentityCenter service

Testing Connectivity from Command Line

LDAP Test with PowerShell

# Test basic LDAP connectivity
$ldap = New-Object System.DirectoryServices.DirectoryEntry(
    "LDAP://dc01.corp.local:389/DC=corp,DC=local",
    "svc_idsync@corp.local",
    "YourPasswordHere"
)
$searcher = New-Object System.DirectoryServices.DirectorySearcher($ldap)
$searcher.Filter = "(objectClass=user)"
$searcher.PageSize = 10
$results = $searcher.FindAll()
Write-Host "Found $($results.Count) users"

Port Test with PowerShell

# Test multiple ports at once
$ports = @(389, 636, 3268, 3269)
foreach ($port in $ports) {
    $result = Test-NetConnection dc01.corp.local -Port $port -WarningAction SilentlyContinue
    Write-Host "Port $port : $($result.TcpTestSucceeded)"
}

When to Involve Your Network Team

Escalate to your network team if:

• Port tests fail between the IdentityCenter server and the domain controller
• Connections work intermittently (may indicate a flapping firewall rule or load balancer issue)
• LDAPS certificate issues persist after installing the CA certificate (may need network inspection/decryption device configuration)
• Connections work from one server but not another on the same network (routing or VLAN issue)
• Queries timeout consistently despite the DC being reachable (may indicate packet inspection or deep packet inspection interfering with LDAP traffic)

Viewing Connection Test Logs

IdentityCenter records connection test results for diagnostic purposes:

1. Navigate to Administration > Connections
2. Click on the failing connection
3. Click Test Connection
4. Expand the Details section to see step-by-step results including error messages, stack traces, and timing

Next Steps

• Creating a Connection -- Review your connection settings
• Connecting to Entra ID -- Entra ID-specific setup steps
• Multi-Forest Setup -- Cross-forest connectivity requirements
• Sync Troubleshooting -- When connections work but sync fails
• System Requirements -- Verify port and network requirements