Certificates for Workload Balancing

Citrix Hypervisor and Workload Balancing communicate over HTTPS. During Workload Balancing Configuration, the wizard automatically creates a self-signed test certificate. This self-signed test certificate lets Workload Balancing establish a TLS connection to Citrix Hypervisor. By default, Workload Balancing creates this TLS connection with Citrix Hypervisor automatically. You do not need to perform any certificate configurations during or after configuration for Workload Balancing to create this TLS connection.

Note:

The self-signed certificate is a placeholder to facilitate HTTPS communication and is not from a trusted certificate authority. For added security, we recommend using a certificate signed from a trusted certificate authority.

To use a certificate from another certificate authority, such as a signed one from a commercial authority, you must configure Workload Balancing and Citrix Hypervisor to use it.

By default, Citrix Hypervisor does not validate the identity of the certificate before it establishes a connection to Workload Balancing. To configure Citrix Hypervisor to check for a specific certificate, export the root certificate that was used to sign the certificate. Copy the certificate to Citrix Hypervisor and configure Citrix Hypervisor to check for it when a connection to Workload Balancing is made. Citrix Hypervisor acts as the client in this scenario and Workload Balancing acts as the server.

Depending on your security goals, you can either:

• Configure Citrix Hypervisor to verify the self-signed certificate.

• Configure Citrix Hypervisor to verify a certificate-authority certificate.

Note:

Certificate verification is a security measure designed to prevent unwanted connections. Workload Balancing certificates must meet strict requirements or the certificate verification doesn’t succeed. When certificate verification fails, Citrix Hypervisor doesn’t allow the connection.

For certificate verification to succeed, you must store the certificates in the specific locations in which Citrix Hypervisor expects to find the certificates.

Configure Citrix Hypervisor to verify the self-signed certificate

You can configure Citrix Hypervisor to verify that the Citrix Workload Balancing self-signed certificate is authentic before Citrix Hypervisor permits Workload Balancing to connect.

Important:

To verify the Citrix Workload Balancing self-signed certificate, you must connect to Workload Balancing using its host name. To find the Workload Balancing host name, run the hostname command on the virtual appliance.

To configure Citrix Hypervisor to verify the self-signed certificate, complete the following steps:

1. Copy the self-signed certificate from the Workload Balancing virtual appliance to the pool master. The Citrix Workload Balancing self-signed certificate is stored at /etc/ssl/certs/server.pem. Run the following command on the pool master:

   scp root@<wlb-ip>:/etc/ssl/certs/server.pem wlb.pem
   <!--NeedCopy-->
   

2. If you receive a message stating that the authenticity of wlb-ip cannot be established, type yes to continue.

3. Enter Workload Balancing virtual appliance root password when prompted. The certificate is copied to the current directory.

4. Install the certificate. Run the following command in the directory where you copied the certificate:

   xe pool-certificate-install filename=wlb.pem
   <!--NeedCopy-->
   

5. Verify the certificate was installed correctly by running the following command on the pool master:

   xe pool-certificate-list
   <!--NeedCopy-->
   

   If you installed the certificate correctly, the output of this command includes the exported root certificate. Running this command lists all installed TLS certificates, including the certificate you installed.

6. To synchronize the certificate from the master to all servers in the pool, running the following command on the pool master:

   xe pool-certificate-sync
   <!--NeedCopy-->
   

   Running the pool-certificate-sync command on the master synchronizes the certificate and certificate revocation lists on all the pool servers with the master. This action ensures all servers in the pool use the same certificates.

   There is no output from this command. However, the next step does not work if this one did not work successfully.

7. Instruct Citrix Hypervisor to verify the certificate before connecting to the Workload Balancing virtual appliance. Run the following command on the pool master:

   xe pool-param-set wlb-verify-cert=true uuid=uuid_of_pool
   <!--NeedCopy-->
   

   Tip:

   Pressing the Tab key automatically populates the UUID of the pool.

8. (Optional) To verify this procedure worked successfully, perform the following steps:

   1. To test if the certificate synchronized to the other servers in the pool, run the pool-certificate-list command on those servers.

   2. To test if Citrix Hypervisor was set to verify the certificate, run the pool-param-get command with the param-name=wlb-verify-cert parameter. For example:

      xe pool-param-get param-name=wlb-verify-cert uuid=uuid_of_pool
      <!--NeedCopy-->
      

Configure Citrix Hypervisor to verify a certificate-authority certificate

You can configure Citrix Hypervisor to verify a certificate signed by a trusted certificate authority.

For trusted authority certificates, Citrix Hypervisor requires an exported certificate or certificate chain (the intermediate and root certificates) in .pem format that contains the public key.

If you want Workload Balancing to use a trusted authority certificate, do the following tasks:

1. Obtain a signed certificate from the certificate authority.

2. Specify and apply the new certificate.

3. Import the certificate chain into the pool.

Before beginning these tasks, ensure:

• You know the IP address for the Citrix Hypervisor pool master.

• Citrix Hypervisor can resolve the Workload Balancing host name. (For example, you can try pinging the Workload Balancing FQDN from the Citrix Hypervisor console for the pool master.)

Obtain a signed certificate from the certificate authority

To obtain a certificate from a certificate authority, you must generate a Certificate Signing Request (CSR). On the Workload Balancing virtual appliance, create a private key and use that private key to generate the CSR.

Guidelines for specifying the Common Name

The Common Name (CN) you specify when creating a CSR must exactly match the FQDN of your Workload Balancing virtual appliance. It must also match the FQDN or IP address you specified in the Address box in the Connect to WLB Server dialog box.

To ensure the name matches, specify the Common Name using one of these guidelines:

• Specify the same information for the certificate’s Common Name as you specified in the Connect to WLB Server dialog.

  For example, if your Workload Balancing virtual appliance is named wlb-vpx.yourdomain, specify wlb-vpx.yourdomain in the Connect to WLB Server dialog and provide wlb-vpx.yourdomain as the Common Name when creating the CSR.

• If you connected your pool to Workload Balancing by IP address, use the FQDN as the Common Name and the IP address as a Subject Alternative Name (SAN). However, this approach might not work in all situations.

Create a private key file

On the Workload Balancing virtual appliance, complete the following steps:

1. Create a private key file:

   openssl genrsa -des3 -out privatekey.pem 2048
   <!--NeedCopy-->
   

2. Remove the password:

   openssl rsa -in privatekey.pem -out privatekey.nop.pem
   <!--NeedCopy-->
   

Note:

If you enter the password incorrectly or inconsistently, you might receive some messages indicating that there is a user interface error. You can ignore the message and rerun the command to create the private key file.

Generate the Certificate Signing Request

On the Workload Balancing virtual appliance, complete the following steps:

1. Create the Certificate Signing Request (CSR) using the private key:

   openssl req -new -key privatekey.nop.pem -out csr
   <!--NeedCopy-->
   

2. Follow the prompts to provide the information necessary to generate the CSR:

   Country Name. Enter the TLS Certificate country codes for your country. For example, CA for Canada or JM for Jamaica. You can find a list of TLS Certificate country codes on the web.

   State or Province Name (full name). Enter the state or province where the pool is located. For example, Massachusetts or Alberta.

   Locality Name. The name of the city where the pool is located.

   Organization Name. The name of your company or organization.

   Organizational Unit Name. Enter the department name. This field is optional.

   Common Name. Enter the FQDN of your Workload Balancing server. This value must match the name the pool uses to connect to Workload Balancing. For more information, see Guidelines for specifying the Common Name.

   Email Address. This email address is included in the certificate when you generate it.

3. Provide optional attributes or click Enter to skip providing this information.

   The CSR request is saved in the current directory and is named csr.

4. Display the CSR in the console window by running the following commands in the Workload Balancing appliance console:

   cat csr
   <!--NeedCopy-->
   

5. Copy the entire CSR and use it to request the certificate from the certificate authority.

Specify and apply the new certificate

Use this procedure to specify Workload Balancing use a certificate from a certificate authority. This procedure installs the root and (if available) intermediate certificates.

To specify a new certificate, complete the following steps:

1. Download the signed certificate, root certificate and, if the certificate authority has one, the intermediate certificate from the certificate authority.

2. If you didn’t download the certificates directly to the Workload Balancing virtual appliance, copy them across by using one of the following methods:

   • From a Windows computer, use WinSCP or another copying utility.

     For the host name, you can enter the IP address and leave the port at the default. The user name and password are typically root and whatever password you set during configuration.

   • From a Linux computer to the Workload Balancing appliance, use SCP or another copying utility. For example:

      scp root_ca.pem root@wlb-ip:/path_on_your_WLB
      <!--NeedCopy-->
     

3. On the Workload Balancing virtual appliance, merge the contents of all the certificates (root certificate, intermediate certificate - if it exists, and signed certificate) into one file. You can use the following command:

   cat signed_cert.pem intermediate_ca.pem root_ca.pem > server.pem
   <!--NeedCopy-->
   

4. Rename the existing certificate and key by using the move command:

   mv /etc/ssl/certs/server.pem /etc/ssl/certs/server.pem_orig
   mv /etc/ssl/certs/server.key /etc/ssl/certs/server.key_orig
   <!--NeedCopy-->
   

5. Copy the merged certificate:

   mv server.pem /etc/ssl/certs/server.pem
   <!--NeedCopy-->
   

6. Copy the private key created previously:

   mv privatekey.nop.pem /etc/ssl/certs/server.key
   <!--NeedCopy-->
   

7. Make the private key readable only by root. Use the chmod command to fix permissions.

   chmod 600 /etc/ssl/certs/server.key
   <!--NeedCopy-->
   

8. Restart stunnel:

   killall stunnel
   stunnel
   <!--NeedCopy-->
   

Import the certificate chain into the pool

After you obtain the certificates, import them onto the Citrix Hypervisor pool master. Synchronize the servers in the pool to use those certificates. Then you can configure Citrix Hypervisor to check the certificate identity and validity each time Workload Balancing connects to a server.

1. Copy the signed certificate, root certificate and, if the certificate authority has one, the intermediate certificate from the certificate authority onto the Citrix Hypervisor pool master.

2. Install the root certificate on the pool master:

   xe pool-certificate-install filename=root_ca.pem
   <!--NeedCopy-->
   

3. If applicable, install the intermediate certificate on the pool master:

   xe pool-certificate-install filename=intermediate_ca.pem
   <!--NeedCopy-->
   

4. Verify both the certificates installed correctly by running this command on the pool master:

   xe pool-certificate-list
   <!--NeedCopy-->
   

   Running this command lists all installed TLS certificates. If the certificates installed successfully, they appear in this list.

5. Synchronize the certificate on the pool master to all servers in the pool:

   xe pool-certificate-sync
   <!--NeedCopy-->
   

   Running the pool-certificate-sync command on the master synchronizes the certificates and certificate revocation lists on all the pool servers with the pool master. This action ensures all servers in the pool use the same certificates.

6. Instruct Citrix Hypervisor to verify a certificate before connecting to the Workload Balancing virtual appliance. Run the following command on the pool master:

   xe pool-param-set wlb-verify-cert=true uuid=uuid_of_pool
   <!--NeedCopy-->
   

   Tip:

   Pressing the Tab key automatically populates the UUID of the pool.

7. If you specified an IP address in the Connect to WLB dialog before you enabled certificate verification, you might be prompted to reconnect the pool to Workload Balancing.

   Specify the FQDN for the Workload Balancing appliance in Address in the Connect to WLB dialog exactly as it appears in the certificate’s Common Name. Enter the FQDN to ensure that the Common Name matches the name that Citrix Hypervisor uses to connect.

Troubleshooting

• Disable certificate verification if your pool can’t connect to Workload Balancing:

  1. Get the pool UUID:

     xe pool-list
     <!--NeedCopy-->
     

  2. Disable certificate verification:

     xe pool-param-set wlb-verify-cert=false uuid=uuid_of_pool
     <!--NeedCopy-->
     

  If your pool can connect to Workload Balancing with certificate verification turned off, the issue is with your certificate configuration. If it cannot connect, the issue is with either your Workload Balancing credentials or your network connection. Contact Support or see Troubleshoot Workload Balancing for more information.

• Some commercial certificate authorities provide tools to verify the certificate installed correctly. Consider running these tools if these procedures fail to help isolate the issue. If these tools require specifying a TLS port, specify port 8012 or whatever port you set during Workload Balancing Configuration.

• If the WLB tab shows a connection error, there might be a conflict between the certificate Common Name and the name of the Workload Balancing virtual appliance. The Workload Balancing virtual appliance name and the Common Name of the certificate must match exactly.

For more information, see Troubleshooting.