Issue/Introduction

This article troubleshoots a failed test connection when adding an AD/LDAP server to ZSphere because StartTLS, LDAPS, port, certificate host name, or management-node name resolution does not match. First distinguish StartTLS from LDAPS, then compare server address, port, TLS switch, certificate name, and resolution result.

Symptoms

• Clicking Test connection while adding AD/LDAP reports failure.
• The page might display:

  Cannot connect to LDAP/AD server
  LDAP connection has been closed unexpected

• After TLS is enabled, address or port changes are not rechecked and the test fails.
• With ldaps://IP:636, connection might fail because the certificate does not contain the IP address.

Environment

• Product: ZSphere
• Versions: 4.x and 5.x
• Components: AD/LDAP authentication and user synchronization
• Server type: WindowsAD
• Deployment: ZSphere integrated with an external AD/LDAP server
• Connection method: StartTLS or LDAPS

Possible causes

This symptom can be caused by one or more of the following:

• StartTLS uses a wrong address/port combination such as ldap://<AD address>:636 with TLS enabled.
• LDAPS uses ldaps://<AD address>:636 by IP, but the server certificate does not contain that IP as a SAN.
• The certificate is bound to a domain name that the ZSphere management node cannot resolve.
• Enabling TLS automatically changes the UI port and the address is not rechecked against the actual method.
• Base DN, user DN, login attribute, filter, binding account, or password is incorrect.

Resolution

Perform the checks in order and confirm each state or next action.

1. Confirm the connection method

• Check: Whether the site intends to use StartTLS or LDAPS.
• UI path: On the ZSphere AD/LDAP add page, inspect address, port, and TLS.
• Expected result: Method and address match:

  StartTLS = ldap://<AD-address>:389 + TLS enabled
  LDAPS    = ldaps://<AD-certificate-domain>:636 + TLS enabled

• Exception handling: Correct mismatched address, port, and TLS in step 2 or 3.

2. Check StartTLS

• Check: StartTLS uses ordinary LDAP port 389 and upgrades the same connection to TLS.
• UI path: On the ZSphere AD/LDAP add page, check:

  Server type: WindowsAD
  Server address: ldap://<AD-address>:389
  TLS: enabled

• Expected result: Address remains ldap://<AD address>:389 and the test succeeds.
• Exception handling: Change ldap://<AD address>:636 with TLS enabled back to:

  ldap://<AD-address>:389

ldap://<AD address>:636 + TLS enabled sends StartTLS to an LDAPS port. The server usually closes the connection and might produce LDAP connection has been closed unexpected.

3. Check LDAPS

• Check: LDAPS uses TLS/SSL from connection establishment and accesses the certificate's domain name.
• UI path: On the ZSphere AD/LDAP add page, check:

  Server type: WindowsAD
  Server address: ldaps://<AD-certificate-domain>:636
  TLS: enabled

• Expected result: Address uses ldaps://, the certificate domain, and port 636, and the test succeeds.
• Exception handling: If ldaps://<AD server IP>:636 is used without that IP in the certificate, change it to:

  ldaps://<AD-certificate-domain>:636

4. Check whether the management node resolves the certificate domain

• Check: The ZSphere management node resolves the certificate domain to the correct IP.
• Location: Run on the management node:

  getent hosts <AD-certificate-domain>

• Expected result: The command returns the AD/LDAP server IP. For example:

  <AD-server-ip> <AD-certificate-domain>

• Exception handling: If there is no result, configure DNS, or, only with explicit customer approval, temporarily add hosts resolution:

  echo "<AD-server-ip> <AD-certificate-domain>" >> /etc/hosts
  getent hosts <AD-certificate-domain>

After resolution works, test again in ZSphere.

5. Verify basic AD/LDAP parameters

• Check: Basic AD/LDAP parameters.
• UI path: On the ZSphere AD/LDAP add page, check:

  Base DN: <base-dn>
  User DN: <bind-user-dn>
  Login attribute: <login-attribute>
  Filter: <user-filter>

• Expected result: Values match the customer AD/LDAP environment and the binding credentials are correct.
• Exception handling: If the DN, login attribute, filter, or password is incorrect, have the customer's AD/LDAP administrator confirm the correct value, and then enter it again. Never place a plaintext customer password in delivery documents, KB attachments, or screenshots.

6. Retest and collect failure information

• Check: Retest after correction and record evidence if it still fails.
• UI path: Click Test connection on the ZSphere AD/LDAP add page.
• Expected result: The test succeeds and users can be synchronized after saving according to site policy.
• Exception handling: If failure remains, submit:
• ZSphere version.
• AD/LDAP server type and version.
• Current address, port, and TLS state.
• Base DN, user DN, login attribute, and filter, with password redacted.
• Management-node getent hosts <AD certificate domain> output.
• ZSphere error and task time.
• Management-node logs for the test time.

Additional information

• Key differences:

• If ordinary LDAP port 389 is available and StartTLS passes, prefer:

  ldap://<AD-address>:389 + TLS enabled

• If LDAPS is required, first confirm the server certificate and management-node DNS, then use:

  ldaps://<AD-certificate-domain>:636 + TLS enabled