Product Documentation

Overview of the Certificate Signing Request

Oct 20, 2015

Before you can upload a certificate to App Controller, you need to generate a Certificate Signing Request (CSR) and private key. You generate the CSR in the Certificate Signing Request dialog box that you open from the Certificates panel in the App Controller management console. After you create the .csr file, you copy the certificate contents and submit them to the Certificate Authority (CA) web site for signing. The CA signs the certificate and returns it to you at the e-mail address you provided. When you receive the signed certificate, you can install it on App Controller.

To provide secure communications by using SSL or TLS, App Controller requires a server certificate. A summary of the steps for obtaining and installing a server certificate on App Controller are as follows:

  • Generate a CSR in the management console.
    Important: When you create the CSR, do not create another CSR. There is a private key associated with the CSR that you send to the CA for signing. If you create another CSR, the private key for the first CSR is erased and you will not be able to install the signed certificate on App Controller. When you install the signed certificate, App Controller automatically pairs it with the private key.
  • Copy the certificate contents and submit them to a CA Web site for signing.
  • When you receive the signed certificate file from your CA, upload the certificate on the Certificates panel in the management console. The certificate is automatically converted to the Privacy Enhanced Mail (PEM) format, which is required by App Controller.

Password-Protected Private Keys

Private keys that are generated with the CSR are stored in an encrypted and password-protected format on App Controller. When creating the CSR, you are asked to provide a password for the private key. The password is used to protect the private key from tampering and is also required when restoring a saved configuration to App Controller. Passwords are used whether the private key is encrypted or unencrypted.

To create a CSR

To provide secure communication by using SSL or TLS, a server certificate is required on App Controller. Before you can upload a certificate to App Controller, you need to generate a CSR and private key. You configure settings as shown in the following figure.

Creating a Certificate Signing request
  1. In the App Controller management console, click the Settings tab.
  2. In the left panel, under System Configuration, click Certificates.
  3. In the Certificates panel, click New and in Certificate Signing Request, type the required information:
    • In Key Length (required), select the encryption strength.
    • In Common name (required), type the host name or the fully qualified domain name (FQDN) of App Controller as it appears on the Network Connectivity panel.
    • In Email, type the email address for the contact person at your company.
    • In Description, type a description for the CSR.
    • In Company name, type the name of your company or organization.
    • In Department name, type the name of the department that will use the certificate.
    • In City, type the name of the city in which your company or organization is located.
    • In State, type the full name of the state where your company is located.
    • In Country Code (required), select the code for your country, such as United States.
  4. Click Save.

    App Controller creates the CSR. A dialog box that contains the contents of the CSR opens.

  5. Copy the certificate contents from the dialog box and then paste the content into the appropriate area on the Certificate Authority web site.

    The certificate provider returns a signed certificate to you by e-mail. When you receive the signed certificate, install it on App Controller.

You can create up to three CSRs. You can view or delete existing CSRs, and you can also choose to sign a CSR so that you can use the certificate immediately.

To import a signed server certificate to App Controller

When you receive the signed certificate from the Certificate Authority (CA), you can upload the certificate to App Controller. The file can be a Privacy Enhanced Mail (PEM) or Personal Information Exchange (PKCS#12) file, which includes both a server certificate and its password-protected private key.

  1. In the App Controller management console, click the Settings tab.
  2. In the left pane, under System Configuration, click Certificates.
  3. Click Import and then select Server (.pem) to import a CA signed root certificate.
  4. In the Upload dialog box, click Browse, navigate to the certificate and then click Open.

Installing Root Certificates on App Controller

After the Certificate Authority (CA) signs your server certificate, the CA returns it to you. If the CA provides the server certificate in PEM format, the CA might also send the root certificate. You need to install the root certificate on App Controller along with the server certificate.

You might also need to install root certificates for applications you configure on App Controller. Each root certificate must match the fully qualified domain name (FQDN) of the server running the application.

To install a root certificate

  1. In the App Controller management console, click the Settings tab.
  2. In the left pane, under System Configuration, click Certificates.
  3. Click Import and then select Trusted (.pem) to import a CA-signed root certificate.
  4. In the Upload dialog box, click Browse, navigate to the certificate and then click Open.

To view the details of a certificate

If you encounter any problems with a certificate, you might want to verify the issuer of the certificate. You can see this information, as well as other details about every certificate you install on App Controller, in the App Controller management console.

  1. In the App Controller management console, click the Settings tab.
  2. In the left pane, under System Configuration, click Certificates.
  3. Under All Certificates, select a certificate and then click Details.
  4. In the dialog box that opens, view certificate details, subject name, and issuer name for the selected certificate and then click Close.

To export a certificate

You might need to export certificates when migrating to a new App Controller VM, backing up an App Controller VM, and sharing certificates between a pair of App Controller VMs used for high availability. You can export an existing server certificate and its corresponding password-protected private key to a file. You can only export certificates in Privacy Enhanced Mail (PEM) format. You can also export a SAML certificate for use with applications that required an App Controller SAML certificate, such as Google Apps.

  1. In the App Controller management console, click the Settings tab.
  2. In the left pane, under System Configuration, click Certificates.
  3. In the table, select the certificate to export and then click Export.
  4. In the Export Certificate dialog box, in Password and Confirm Password, type the password that will be used to encrypt the exported certificate and then click OK.

Configuring Certificates for SAML Applications

Some SAML applications, such as ShareFile, Google Apps, and Echosign, require a certificate to communicate with App Controller. After you add the application in App Controller and configure application settings, you download a SAML certificate from App Controller. When you configure settings in the SAML application, you upload the certificate to the application. By doing so, you ensure secure connections between the application and App Controller.

App Controller supports installation of one SAML certificate on App Controller. When you first install App Controller, a SAML certificate is created and appears in the Certificates panel.

The SAML certificate is called AppController.example.com. If you want to use a custom SAML certificate, you need to upload a .pem certificate that contains only the certificate and private key.

Important: Do not include any chain certificates with the SAML certificate.

When you install the new SAML certificate, App Controller removes any previously installed certificates, including the AppController.example.com SAML certificate created during App Controller installation. Only one SAML certificate can reside on App Controller.

You can download a SAML certificate by using one of the two following methods:

  • If you download the SAML certificate for backup, Citrix recommends creating a password to encrypt the certificate with a private key.
  • If you download the SAML certificate for use with SaaS applications, do not include the password. Private keys should not be included with the certificate in this instance.

To download a SAML certificate

  1. In the App Controller management console, click the Settings tab.
  2. In the left pane, under System Configuration, click Certificates.
  3. Under Certificates > All Certificates, select the SAML certificate and then click Export.
  4. In the Export Certificate dialog box, in Password and Confirm Password, enter the password for the certificate.

    Only supply the password if you are backing up the certificate and storing it on your computer.

  5. To export the private key with the certificate, click Export with private key and then click OK to save the certificate to your computer.

    Select this option only if you are backing up the certificate.

  6. Navigate to the location on your computer where you want to save the certificate and then click Save.

To install a certificate for an application

To allow users to establish communication with an application that communicates over SSL, such as Active Directory over secure LDAP, you need to install a root certificate on App Controller and then associate the certificate with the application. The root certificate validates the application server's identity and allows users to access the application. You must install a root certificate for each application you add to App Controller.

  1. In the App Controller management console, click the Settings tab.
  2. In the left pane, under System Configuration, click Certificates.
  3. Click Import and then click Saml (.pem).
  4. In the Upload dialog box, click Browse, navigate to the certificate on your computer, and then click Open.