LDAP and LDAPS Troubleshooting

Section: Troubleshooting | Article 49
Audience: System Administrators
Last Updated: 2026-04-07

---

Overview

This article covers issues with LDAP and LDAPS (LDAP over TLS) connections used by the Active Directory module and Entra ID hybrid scenarios. For general troubleshooting, see General Troubleshooting.

---

Server Unavailable (LDAP/LDAPS Connection Failed)

Symptoms

• AD module status shows "error"
• Log shows LdapException: The LDAP server is unavailable
• Grant operations fail with "Cannot connect to directory"

Diagnosis

Step 1: Test basic network connectivity.

PowerShell (Windows):

# Test LDAP (port 389)
Test-NetConnection -ComputerName "dc01.corp.local" -Port 389

# Test LDAPS (port 636)
Test-NetConnection -ComputerName "dc01.corp.local" -Port 636

# Test Global Catalog (port 3268 / 3269)
Test-NetConnection -ComputerName "dc01.corp.local" -Port 3268

Linux:

# Test LDAP
nc -zv dc01.corp.local 389

# Test LDAPS
nc -zv dc01.corp.local 636

# Or using openssl for LDAPS (also tests TLS handshake)
openssl s_client -connect dc01.corp.local:636 -showcerts </dev/null 2>/dev/null | head -20

Step 2: Verify DNS resolution:

# PowerShell
Resolve-DnsName "dc01.corp.local"
Resolve-DnsName "_ldap._tcp.corp.local" -Type SRV

# Linux
nslookup dc01.corp.local
dig _ldap._tcp.corp.local SRV

Step 3: If the server is reachable but LDAPS fails, see Certificate Validation Failed below.

Common Causes

Cause	Solution
Domain controller is down	Check DC health; try another DC
Firewall blocking port 389/636	Add firewall rule for LDAP/LDAPS ports
DNS not resolving DC hostname	Fix DNS or use IP address in module config
Wrong port configured	Verify ldapPort in module configuration

---

Invalid Credentials

Symptoms

• Log shows LdapException: Invalid credentials (49)
• Module health check fails with authentication error

Diagnosis

Step 1: Verify the service account credentials.

PowerShell (test LDAP bind):

$cred = Get-Credential -Message "Enter RP-PAM service account credentials"
$ldapServer = "dc01.corp.local"

try {
    $searcher = New-Object DirectoryServices.DirectorySearcher
    $searcher.SearchRoot = New-Object DirectoryServices.DirectoryEntry(
        "LDAP://$ldapServer", $cred.UserName, $cred.GetNetworkCredential().Password
    )
    $searcher.FindOne()
    Write-Host "LDAP bind successful" -ForegroundColor Green
} catch {
    Write-Host "LDAP bind failed: $_" -ForegroundColor Red
}

Linux (using ldapsearch):

ldapsearch -x -H ldap://dc01.corp.local \
  -D "CN=rppam-svc,OU=Service Accounts,DC=corp,DC=local" \
  -W -b "DC=corp,DC=local" "(objectClass=top)" dn | head -5

For LDAPS:

ldapsearch -x -H ldaps://dc01.corp.local \
  -D "CN=rppam-svc,OU=Service Accounts,DC=corp,DC=local" \
  -W -b "DC=corp,DC=local" "(objectClass=top)" dn | head -5

Step 2: Check for common credential issues:

Issue	Symptom	Solution
Password expired	Error code 49, sub-code 532	Reset the service account password in AD and update RP-PAM config
Account locked out	Error code 49, sub-code 775	Unlock the account in AD; check for misconfigured scripts causing lockouts
Account disabled	Error code 49, sub-code 533	Re-enable the account in AD
Wrong username format	Error code 49	Use the full DN or UPN format: rppam-svc@corp.local

Step 3: Update the credentials in RP-PAM:

# Update via API
$body = @{
    config = @{
        adminUser     = "rppam-svc@corp.local"
        adminPassword = "NewSecurePassword"
    }
} | ConvertTo-Json -Depth 3

Invoke-RestMethod -Uri "https://rppam.corp.local:7101/api/v1/modules/$moduleId" `
    -Method PATCH `
    -Headers @{ Authorization = "Bearer $adminJwt" } `
    -ContentType "application/json" `
    -Body $body

---

Certificate Validation Failed

Symptoms

• LDAPS connection fails
• Log shows The remote certificate is invalid according to the validation procedure
• Or: CERTIFICATE_VERIFY_FAILED

Cause

The domain controller's LDAPS certificate is not trusted by the RP-PAM server. This commonly happens with: - Self-signed certificates - Internal CA certificates not in the trust store - Expired certificates - Certificate subject name mismatch

Diagnosis

Step 1: Examine the DC's certificate.

PowerShell:

$tcpClient = New-Object System.Net.Sockets.TcpClient("dc01.corp.local", 636)
$sslStream = New-Object System.Net.Security.SslStream($tcpClient.GetStream(), $false,
    { param($s, $c, $ch, $e) return $true })
$sslStream.AuthenticateAsClient("dc01.corp.local")
$cert = $sslStream.RemoteCertificate

Write-Host "Subject: $($cert.Subject)"
Write-Host "Issuer: $($cert.Issuer)"
Write-Host "Valid From: $($cert.GetEffectiveDateString())"
Write-Host "Valid To: $($cert.GetExpirationDateString())"
Write-Host "Thumbprint: $($cert.GetCertHashString())"

$sslStream.Close()
$tcpClient.Close()

Linux (openssl):

openssl s_client -connect dc01.corp.local:636 -showcerts </dev/null 2>/dev/null | \
  openssl x509 -noout -subject -issuer -dates -fingerprint

Step 2: Identify the issue:

Issue	What You'll See	Solution
Expired certificate	Valid To date is in the past	Renew the DC's LDAPS certificate
Untrusted CA	Issuer is an internal CA	Install the CA cert on the RP-PAM server (see below)
Name mismatch	Subject CN doesn't match the hostname used	Use the hostname that matches the cert CN, or issue a new cert
Self-signed	Subject == Issuer	Install the self-signed cert as trusted (see below)

Installing the CA Certificate

Windows:

# Import the CA certificate to the machine trust store
Import-Certificate -FilePath "C:\certs\internal-ca.cer" `
    -CertStoreLocation "Cert:\LocalMachine\Root"

Linux (Debian/Ubuntu):

sudo cp /tmp/internal-ca.crt /usr/local/share/ca-certificates/internal-ca.crt
sudo update-ca-certificates

Linux (RHEL/Fedora):

sudo cp /tmp/internal-ca.crt /etc/pki/ca-trust/source/anchors/internal-ca.crt
sudo update-ca-trust

After installing the CA cert, restart RP-PAM:

sudo systemctl restart rppam

Alternative: Skip Certificate Validation (Not Recommended)

For testing only, you can disable LDAPS certificate validation in the module config:

{
  "config": {
    "ldapVerifyCertificate": false
  }
}

Warning: Disabling certificate validation makes the LDAPS connection vulnerable to man-in-the-middle attacks. Do not use this in production.

---

Delegation Issues

Symptoms

• RP-PAM can authenticate to LDAP but cannot modify group memberships
• Log shows LdapException: Insufficient access rights (50)
• AD module grant operations fail

Cause

The RP-PAM service account does not have delegated permissions to manage the target groups or OUs.

Diagnosis

Step 1: Check what the service account can do:

# Test reading a group
Get-ADGroup -Identity "PAM-Target-Group" -Server "dc01.corp.local" `
    -Credential (Get-Credential)

# Test adding a member (dry run — check permissions first)
Get-ADGroup -Identity "PAM-Target-Group" -Properties "nTSecurityDescriptor" |
    Select-Object -ExpandProperty nTSecurityDescriptor |
    Select-Object -ExpandProperty Access |
    Where-Object { $_.IdentityReference -like "*rppam*" } |
    Format-Table IdentityReference, ActiveDirectoryRights, AccessControlType

Step 2: Delegate permissions in Active Directory:

1. Open Active Directory Users and Computers
2. Enable Advanced Features (View menu)
3. Right-click the OU containing the target groups > Delegate Control
4. Add the RP-PAM service account
5. Grant the following permissions:
6. Modify the membership of a group — on the groups OU
7. Read all user information — on the users OU

Alternatively, use PowerShell:

# Grant the service account permission to manage group membership
$ouDN = "OU=PAM-Groups,DC=corp,DC=local"
$serviceAccount = "CORP\rppam-svc"

dsacls $ouDN /I:S /G "${serviceAccount}:WP;member"

Scoping Permissions

For security, delegate permissions only on the OUs that RP-PAM needs to manage, not the entire domain:

Scope	Permission	Why
PAM target groups OU	Modify group membership	Add/remove users during grants
Users OU (or forest)	Read user properties	Look up users for grant operations
Do NOT grant	Domain Admin or Account Operator	Excessive privileges — violates least-privilege

---

LDAP Referral Issues

Symptoms

• Searches return empty results
• Log shows LdapReferralException or references to other domain controllers

Cause

The LDAP query crossed a domain boundary in a multi-domain forest, and the RP-PAM server followed a referral to a DC it cannot reach.

Solution

1. Use Global Catalog ports (3268/3269) instead of standard LDAP ports (389/636) for multi-domain forests:

   {
     "config": {
       "ldapPort": 3268,
       "useLdaps": false
     }
   }
   

   Or for LDAPS Global Catalog:

   {
     "config": {
       "ldapPort": 3269,
       "useLdaps": true
     }
   }
   

2. Disable referral chasing if you only need the local domain:

   {
     "config": {
       "ldapChaseReferrals": false
     }
   }
   

---

Troubleshooting Summary

Problem	Platform	First Check
Server unavailable	Both	Test-NetConnection / nc -zv on port 636
Invalid credentials	Both	Test LDAP bind with service account
Certificate validation	Both	Inspect cert with openssl or PowerShell
Insufficient access	Both	Check delegated permissions in AD
Referral issues	Both	Use Global Catalog ports (3268/3269)

---

Next Steps

• Active Directory Module — AD module setup and configuration
• Service Account Setup (AD) — Configure the AD service account
• General Troubleshooting — Platform-independent issues

---

RP-PAM v1.0.0 — Copyright 2026 Ravenphyre. All rights reserved.