Configure LDAPS
LDAPS is the secure version of the Lightweight Directory Access Protocol (LDAP) where LDAP communications are encrypted using TLS/SSL.
By default, LDAP communications between client and server applications are not encrypted. LDAPS enables you to protect the LDAP query content between the Linux VDA and the LDAP servers.
The following Linux VDA components have dependencies on LDAPS:
- Broker agent: Linux VDA registration with a 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 the Linux VDA
- Configure LDAPS for third-party platforms
- Configure SSSD
- Configure Winbind
- Configure Centrify
- Configure Quest
Note:
You can run the following command to set a monitoring cycle for your LDAP servers. The default value is 15 minutes. Set it to 10 minutes at least.
/opt/Citrix/VDA/bin/ctxreg create -k "HKLM\Software\Citrix\VirtualDesktopAgent" -v "ListOfLDAPServersMonitorPeroid" -t "REG_DWORD" -d "0x0000000f" --force <!--NeedCopy-->
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:
LDAPS is enabled automatically 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.
When you have a multi-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.
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 a trusted 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 on the Linux VDA, run the enable_ldaps.sh script (while logged on as an administrator). To run the enable_ldaps.sh script in a non-interactive mode, export the following variables to your environment:
#CTX_LDAPS_KEYSTORE_PASSWORD=
#CTX_LDAPS_LDAP_SERVERS=
<!--NeedCopy-->
-
To enable LDAP over SSL/TLS with the root CA certificate provided:
/opt/Citrix/VDA/sbin/enable_ldaps.sh -Enable pathToRootCA <!--NeedCopy--> -
To enable LDAP over SSL/TLS with channel binding:
/opt/Citrix/VDA/sbin/enable_ldaps.sh -Enablecb pathToRootCA <!--NeedCopy-->Note:
The root CA certificate for channel binding must be in PEM format. If enabling LDAPS does not create a Python3 virtual environment successfully, create it manually following the instructions at Create a Python3 virtual environment.
To address SSL connection errors that you might encounter when using the pip tool, consider adding the following trusted hosts to the /etc/pip.conf file:
[global]
trusted-host =
pypi.org
files.pythonhosted.org -
To fall back to LDAP without SSL/TLS
/opt/Citrix/VDA/sbin/enable_ldaps.sh -Disable <!--NeedCopy-->
The Java keystore dedicated for LDAPS resides 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
HKLM\Software\Citrix\VirtualDesktopAgent\EnableChannelBinding
<!--NeedCopy-->
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 port 389.
SSSD
Configure the SSSD secure LDAP traffic on port 636 or port 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 /etc/samba/smb.conf and /etc/openldap/ldap.conf (for RHEL) or /etc/ldap/ldap.conf (for Ubuntu). Change the files as follows:
-
smb.conf
ldap ssl = start tls
ldap ssl ads = yes
client ldap sasl wrapping = plain -
ldap.conf
TLS_REQCERT never
Alternately, you can configure secure LDAP by SASL GSSAPI sign and seal, but it cannot coexist with TLS/SSL. To use SASL encryption, change the smb.conf configuration:
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 port 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. 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. We recommend 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.