App Orchestration 2.5 Configuring SSL for App Orchestration 2.5 Prepared by: Andy Zhu Last Updated: July 25, 2014
Contents Introduction... 3 Configure SSL on the App Orchestration configuration server... 3 Task overview... 3 Import the certificate using the App Orchestration configuration wizard... 4 Troubleshooting... 6 Configure SSL on a XenDesktop Delivery Controller... 7 Prerequisites... 7 To configure SSL on a XenDesktop Delivery Controller... 7 Troubleshooting... 10 Configure SSL on a XenApp controller... 10 Prerequisites... 10 To configure SSL on a XenApp controller... 11 Troubleshooting... 13 Configure SSL in a StoreFront server group... 13 Import and bind the certificate with the web console... 13 Bind a certificate that is already installed on StoreFront server... 16 Troubleshooting... 18 Issue: The certificate file cannot be found at the SSL certificate location... 18 Issue: Certificate password is incorrect... 18 Issue: Certificate exists but not in the right certificate store... 18 Issue: Certificate does not exist at all but the administrator select the Use Existing option... 19 Issue: Certificate friendly name does not match... 19 Page 2
Introduction In a typical App Orchestration deployment, you deploy certificates on the App Orchestration configuration server and StoreFront servers to secure communication between the App Orchestration agent (called CamAgent) and the App Orchestration configuration server, and between Citrix Receiver and Storefront servers. However, if you also need to secure the communication between the XML Service running on XenApp or XenDesktop controllers and Storefront servers, you can install certificates on the XenApp and XenDesktop controllers in your App Orchestration deployment. This document explains how to use SSL certificates in a typical App Orchestration environment to secure the communication between Storefront servers and XenApp or XenDesktop contollers. Configure SSL on the App Orchestration configuration server The SSL certificate that you install on the App Orchestration configuration server performs the following functions: Secure communication between the App Orchestration agent that is installed on each XenApp or XenDesktop controller and the domain agent that is installed on a dedicated machine which resides behind a NAT-enabled device. Secure communication between the App Orchestration web console, for performing App Orchestration administrative operations, and the App Orchestration configuration server. Task overview To configure SSL on the App Orchestration server, you perform the following tasks: 1. Install the SSL certificate on the App Orchestration server. This required as the App Orchestration installation process does not include installing the certificate. 2. Enable the App Orchestration agent and the domain agent to trust the certificate installed on the configuration server. To achieve this trust, the root Certificate Authority (CA) for the certificate on the configuration server must reside within the Trusted Root Certificate Authorities node of the local machine certificate store on the XenApp, XenDesktop, StoreFront, or domain agent server. Page 3
The following illustration shows the CA for the certificate on the configuration server, called DC-CA, which is located in the Trusted Root Certificate Authorities path. 3. Import the certificate during App Orchestration installation. When you install the App Orchestration configuration server, the server configuration wizard prompts you to select the certificate you previously installed. Import the certificate using the App Orchestration configuration wizard 1. Click Browse certificate installed on the local machine to locate certificates installed on the server. Page 4
2. Select the certificate you want to use on the configuration server. After you select the certificate, the configuration wizard is ready to bind it during the installation. Page 5
Troubleshooting Issue: The certificate on the configuration server is not trusted by the App Orchestration and domain agents. Symptoms: The App Orchestration web console displays a warning for the server s health status. When you hover the mouse over the warning icon, a warning message appears. Additionally, the XenApp, XenDesktop, or StoreFront servers do not execute any workflows and the following message is logged in Event Viewer on these servers: Page 6
Corrective Actions: Make sure the certificate is trusted by the App Orchestration agent on the XenApp, XenDesktop, and StoreFront servers and restart the Citrix App Orchestration Agent service. Configure SSL on a XenDesktop Delivery Controller By default, Storefront servers communicate with the XML Service running on XenDesktop Delivery Controllers using HTTP (port 80). To deploy a more secure environment, you can enable the Storefront servers to communicate with the XML Service using HTTPS (port 443). To do this, you install a server certificate on the XenDesktop Delivery Controller. Important: By default, the XML Service on the XenDesktop Delivery Controller listens for HTTP traffic on port 80 and HTTPS traffic on port 443. Do not change these default ports as App Orchestration supports only these ports for HTTP and HTTPS traffic. Prerequisites Before you perform the steps in this section, perform the following tasks: 1. Install a server certificate on the XenDesktop Delivery Controller. The process of importing Sites does not include installing server certificates, so the certificate must exist on the server beforehand. 2. Ensure the StoreFront servers trust the certificate you install on the XenDesktop Delivery Controller. If trust is not established, StoreFront cannot communicate with the XML Service on the XenDesktop Delivery Controller. If communication with the XML Service fails, StoreFront cannot enumerate applications for users when they log on with Citrix Receiver. To configure SSL on a XenDesktop Delivery Controller Perform the steps in this section before you import a XenDesktop Delivery Site into your App Orchestration deployment. 1. On the App Orchestration configuration server, modify the following registry key: a. Launch the Registry Editor. b. Navigate to HKLM\Software\Citrix\CloudAppManagement\Configuration Page 7
c. Create a DWORD value called XmlSSLEnabled and set the value data to 1. 2. On the XenDesktop Delivery Controller, perform the following tasks: a. Install the Web server (IIS) role. b. Install a server certificate. 3. Bind the certificate to the IIS default website. 4. Prepare the server according to the software requirements for Delivery Controllers as described in the document Getting Started with App Orchestration 2.5. Page 8
5. In the Windows Registry, navigate to HKLM\Software\Citrix\CloudAppManagement\Agent. Create a DWORD value called XmlSSLEnabled and set the value data to 1. 6. Import the XenDesktop Delivery Site using the App Orchestration web console. During the creation of delivery groups, the workflow executed on the StoreFront server will configure the HTTPS protocol in the store configuration Page 9
Troubleshooting Issue: The certificate on the XenDesktop controller does not exist or is not bound to the IIS service. Symptom: The web console displays failed New-DeliverySite or Join-DeliverySite workflows. Corrective Actions: Make sure the certificate is installed correctly and bound to the IIS default web site on the XenDesktop controller and retry the workflow. Configure SSL on a XenApp controller By default, the StoreFront server communicates with the XML Service running on the XenApp controller using port 8080. The Citrix XML Service runs in its own process. To deploy a more secure environment, you can enable the Storefront servers to communicate with the XML Service using HTTPS (port 443). To do this, you install a server certificate on the XenApp controller. Note: App Orchestration does not support using SSL Relay for communication between the XML Service and XenApp controllers. Important: By default, the XML Service on the XenApp controller listens for HTTP traffic on port 80 and HTTPS traffic on port 443. Do not change these default ports as App Orchestration supports only these ports for HTTP and HTTPS traffic. Prerequisites Before you perform the steps in this section, perform the following tasks: 1. Install a server certificate on the XenApp controller. The process of importing Sites does not include installing server certificates, so the certificate must exist on the server beforehand. 2. Ensure the StoreFront servers trust the certificate you install on the XenApp controller. If trust is not established, StoreFront cannot communicate with the XML Service on the XenApp controller. If communication with the XML Service fails, StoreFront cannot enumerate applications for users when they log on with Citrix Receiver. Page 10
To configure SSL on a XenApp controller Perform the steps in this section before you import a XenApp Delivery Site into your App Orchestration deployment. 1. On the App Orchestration configuration server, modify the following registry key: a. Launch the Registry Editor. b. Navigate to HKLM\Software\Citrix\CloudAppManagement\Configuration c. Create a DWORD value called XmlSSLEnabled and set the value data to 1. 2. On the XenApp controller, perform the following tasks: a. Install the Web Server (IIS) role. b. Install a server certificate. 3. Bind the certificate to the IIS default website 4. Prepare the server according to the software requirements for Delivery Controllers as described in the document Getting Started with App Orchestration 2.5. Page 11
5. In the Windows Registry, navigate to HKLM\Software\Citrix\CloudAppManagement\Agent. Create a DWORD value called XmlSSLEnabled and set the value data to 1. 6. Import the XenApp Delivery Site using the App Orchestration web console. During the creation of delivery groups, the workflow executed on the StoreFront server will configure the HTTPS protocol in the store configuration Page 12
Troubleshooting Issue: The certificate on the XenApp controller does not exist or is not bound to the IIS service. Symptom: The App Orchestration web console displays failed New-DeliverySite or Join-DeliverySite workflows. Corrective Actions: Make sure the certificate is installed correctly and bind it to the IIS default web site on the XenApp controller and retry the workflow. Configure SSL in a StoreFront server group Certificates that are installed on each server in a StoreFront server group enable HTTPS communication between the StoreFront server and Citrix Receiver running on the user s device. App Orchestration supports the installation and binding of the certificate to the StoreFront server group. When you import the StoreFront servers through the App Orchestration web console, can bind the certificate to the StoreFront Server Group using one of the following methods: Import and bind the certificate using the App Orchestration web console Install the certificate manually and then bind the certificate using the App Orchestration web console Import and bind the certificate with the web console To import and bind the certificate through the App Orchestration web console, ensure the certificate meets following requirements: The certificate file is in.pfx format. The certificate contains the private key password. The certificate is a wildcard certificate. For example, *.domain.com Page 13
1. In the App Orchestration web console, launch the Import StoreFront Server Groups wizard. 2. In Assign SSL Settings, select Assign New. 3. In SSL certificate friendly name, type the friendly name exactly as defined in the Friendly Name property of the SSL certificate. Page 14
4. In SSL certificate location, choose a location for the certificate that can be accessed by the domain credential (either the global shared resource domain credential or the tenant resource domain credential). 5. In Load Balancer URL, ensure the domain of the URL that you enter matches the domain of the certificate installed on the server. Page 15
Bind a certificate that is already installed on StoreFront server Perform the tasks in this section if you have already installed certificates on the StoreFront servers you want to add to a StoreFront server group. To bind the certificate through the App Orchestration web console, ensure the certificate exists in the local machine certificate store on the StoreFront server. 1. From the App Orchestration web console, launch the Import StoreFront Server Group wizard. 2. In Assign SSL certificate, select Use Existing. Page 16
3. In SSL certificate friendly name, type the friendly name exactly as defined in the Friendly Name property of the SSL certificate. 4. In Load Balancer URL, ensure the domain of the URL you enter matches the domain of the certificate installed on the server. Page 17
Troubleshooting Issue: The certificate file cannot be found at the SSL certificate location Symptom: The Install-StoreFrontCertificate workflow fails. Corrective Action: Delete the Storefront server group and re-import StoreFront servers again with the correct certificate path. Issue: Certificate password is incorrect Symptom: The Install-StoreFrontCertificate workflow fails. Correction Action: Delete the StoreFront server group and re-import the StoreFront servers with the correct password for the certificate. Issue: Certificate exists but not in the right certificate store Symptom: The Install-StoreFrontCertificate workflow fails. Corrective Action: Delete the StoreFront server group and re-import the StoreFront servers after the certificate been added to the correct location. Page 18
Issue: Certificate does not exist at all but the administrator select the Use Existing option Symptom: The Install-StoreFrontCertificate workflow fails. Corrective Action: Delete the StoreFront server group and re-import the StoreFront servers after the certificate been added to the correct location. Issue: Certificate friendly name does not match Symptom: The Install-StoreFrontCertificate workflow fails. Corrective Action: Delete the StoreFront server group and re-import the StoreFront servers with correct certificate friendly name. Page 19