Product Documentation

Configure LDAPS

May 22, 2017

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 will 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 in as an administrator):

The syntax for this command includes the following:

  • enable LDAP over SSL/TLS with the root CA certificate provided:
command Copy

/opt/Citrix/VDA/sbin/enable_ldaps.sh -Enable pathToRootCA

  • fallback to LDAP without SSL/TLS
command Copy

/opt/Citrix/VDA/sbin/enable_ldaps.sh -Disable

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

command Copy

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, there are several third-party software components that adhere to the Linux VDA that 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. Make changes to the files as shown below:

config Copy

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:

command Copy

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. For more information, see the Quest authentication article.

Troubleshooting

The following issues might arise when using 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 port(s) 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 (listed above) 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 occurs.

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 Certification is the correct type. Generally speaking, it’s supposed to work with most of the Java Keytool types supported. If it's 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 new keystore.