Product Documentation

Configure LDAPS

Secure LDAP (LDAPS) allows you to enable the Secure Lightweight Directory Access Protocol for your Active Directory managed domains to provide communication over SSL (Secure Socket Layer)/TLS (Transport Layer Security).

By default, LDAP communications between client and server applications are not encrypted. LDAP using SSL/TLS (LDAPS) enables you to protect the LDAP query content between Linux VDA and LDAP servers.

The following Linux VDA components have dependencies on LDAPS:

  • Broker agent: Linux VDA registration to Delivery Controller
  • Policy service: Policy evaluation

Configuring LDAPS involves:

  • Enable LDAPS on the Active Directory (AD)/LDAP server
  • Export the root CA for client use
  • Enable/disable LDAPS on Linux VDA
  • Configure LDAPS for third-party platforms
  • Configure SSSD
  • Configure Winbind
  • Configure Centrify
  • Configure Quest

Enable LDAPS on the AD/LDAP server

You can enable LDAP over SSL (LDAPS) by installing a properly formatted certificate from either a Microsoft certification authority (CA) or a non-Microsoft CA.

Tip:

LDAP over SSL/TLS (LDAPS) is automatically enabled when you install an Enterprise Root CA on a domain controller.

For more information about how to install the certificate and verify the LDAPS connection, see How to enable LDAP over SSL with a third-party certification authority on the Microsoft Support site.

When you have a multi-tier (such as a two-tier or three-tier) certificate authority hierarchy, you do not automatically have the appropriate certificate for LDAPS authentication on the domain controller.

For information about how to enable LDAPS for domain controllers using a multi-tier certificate authority hierarchy, see the LDAP over SSL (LDAPS) Certificate article on the Microsoft TechNet site.

Enable root certificate authority for client use

The client must be using a certificate from a CA that the LDAP server trusts. To enable LDAPS authentication for the client, import the root CA certificate to trust keystore.

For more information about how to export Root CA, see How to export Root Certification Authority Certificate on the Microsoft Support website.

Enable or disable LDAPS on the Linux VDA

To enable or disable LDAPS for Linux VDA, run the following script (while logged on as an administrator):

The syntax for this command includes the following:

  • Enable LDAP over SSL/TLS with the root CA certificate provided:
/opt/Citrix/VDA/sbin/enable_ldaps.sh -Enable pathToRootCA
  • Fallback to LDAP without SSL/TLS
/opt/Citrix/VDA/sbin/enable_ldaps.sh -Disable

The Java keystore dedicated for LDAPS is located in /etc/xdl/.keystore. Affected registry keys include:

HKLM\Software\Citrix\VirtualDesktopAgent\ListOfLDAPServers
HKLM\Software\Citrix\VirtualDesktopAgent\ListOfLDAPServersForPolicy
HKLM\Software\Citrix\VirtualDesktopAgent\UseLDAPS
HKLM\Software\Policies\Citrix\VirtualDesktopAgent\Keystore

Configure LDAPS for third-party platform

Besides the Linux VDA components, several third-party software components that adhere to the VDA might also require secure LDAP, such as SSSD, Winbind, Centrify, and Quest. The following sections describe how to configure secure LDAP with LDAPS, STARTTLS, or SASL sign and seal.

Tip:

Not all of these software components prefer to use SSL port 636 to ensure secure LDAP. And most of the time, LDAPS (LDAP over SSL on port 636) cannot coexist with STARTTLS on 389.

SSSD

Configure the SSSD secure LDAP traffic on port 636 or 389 as per the options. For more information, see the SSSD LDAP Linux man page.

Winbind

The Winbind LDAP query uses the ADS method. Winbind supports only the StartTLS method on port 389. Affected configuration files are ldap.conf and smb.conf. Change the files as follows:

ldap.conf:
TLS_REQCERT never

smb.conf:
ldap ssl = start tls
ldap ssl ads = yes
client ldap sasl wrapping = plain

Alternately, secure LDAP can be configured by SASL GSSAPI sign and seal, but it cannot coexist with TLS/SSL. To use SASL encryption, change the smb.conf configuration:

smb.conf:
ldap ssl = off
ldap ssl ads = no
client ldap sasl wrapping = seal

Centrify

Centrify does not support LDAPS on port 636. However, it does provide secure encryption on port 389. For more information, see the Centrify site.

Quest

Quest Authentication Service does not support LDAPS on port 636, but it provides secure encryption on 389 using a different method.

Troubleshooting

The following issues might arise when you use this feature:

  • LDAPS service availability

    Verify that the LDAPS connection is available on the AD/LDAP server. The port is on 636 by default.

  • Linux VDA registration failed when LDAPS is enabled

    Verify that the LDAP server and ports are configured correctly. Check the Root CA Certificate first and ensure that it matches the AD/LDAP server.

  • Incorrect registry change by accident

    If the LDAPS related keys were updated by accident without using enable_ldaps.sh, it might break the dependency of LDAPS components.

  • LDAP traffic is not encrypted through SSL/TLS from Wireshark or any other network monitoring tools

    By default, LDAPS is disabled. Run /opt/Citrix/VDA/sbin/enable_ldaps.sh to force it.

  • There is no LDAPS traffic from Wireshark or any other networking monitoring tool

    LDAP/LDAPS traffic occurs when Linux VDA registration and Group Policy evaluation occur.

  • Failed to verify LDAPS availability by running ldp connect on the AD server

    Use the AD FQDN instead of the IP Address.

  • Failed to import Root CA certificate by running the /opt/Citrix/VDA/sbin/enable_ldaps.sh script

    Provide the full path of the CA certificate, and verify that the Root CA Certificate is the correct type. Generally speaking, it is supposed to be compatible with most of the Java Keytool types supported. If it is not listed in the support list, you can convert the type first. Citrix recommends the base64 encoded PEM format if you encounter a certificate format problem.

  • Failed to show the Root CA certificate with Keytool -list

    When you enable LDAPS by running /opt/Citrix/VDA/sbin/enable_ldaps.sh, the certificate is imported to /etc/xdl/.keystore, and the password is set to protect the keystore. If you forget the password, you can rerun the script to create a keystore.