HowTo: Importing SSL Certificates on the NetScaler

This blogpost is also posted on the PepperCrew website.
 

There are a lot of different certificate file formats that can be involved in a SSL certificate implementation as explained in my previous blogpost. This blogpost focused on the different methods to create and import these files onto the Citrix NetScaler and showing you how to assign the right SSL certificate to your virtual server for load balancing or gateway services. You can read all about the different certificate (and certificate archives) file formats in my previous post.

With all the instructions included in this blogpost it has become a rather long post, so I’ve added a small index to quickly navigate to the different sections:
     – Creating a private key on the NetScaler
     – Creating the certificate signing request on the NetScaler
     – Creating the certificate signing request with Internet Information Service
     – Importing a PKCS#12 (.pfx file format) certificate store on the NetScaler
     – Importing a PEM certificate store on the NetScaler
     – Importing the root and/or intermediate certificates on the NetScaler
     – Creating the certificate chain on the NetScaler
     – Binding the SSL certificate to a virtual server on the NetScaler

As pointed out correctly by Barry Schiffer in my previous post, working with SSL certificates on the NetScaler starts with the creation of the private key.

Screens	Actions
	Log onto the management console of the NetScaler. Expand Traffic Management in the left pane and select the SSL node.
	In the right pane click on [Create RSA Key] in the SSL Keys section.
	Specify a Key Filename and Key Size, like 1024 or 2048. Make sure the PEM Key Format is selected, as shown in the screen shot. Optionally: Select an appropriate PEM Encoding Algorithm (depends on your organizational policies). Enter a PEM passphrase. Click [Create] and then click [Close].
Note down the PEM passphrase as you will need to provide it later on when you want to import the certificate.
	You can check if the private key is created successfully by clicking on [Manage Certificates/Key/CSRs] in the Tools section of the right pane.
	The private key file should be shown in the list of files.
	To view the content of the private key, select the file and click on [View] to open the file and be able to copy the content or save the file locally.

When a private key is created, you can continue to create a Certificate Signing Request on the NetScaler.

Screens	Actions
	Log onto the management console of the NetScaler. Expand Traffic Management in the left pane and select the SSL node.
	In the right pane click on [Create Certificate Signing Request (CSR)] in the SSL Certificates section.
	Specify a name for the csr file in the Request File Name field. Browse for the private key file, created in the previous paragraph. Select the right encoding type as the Key Format and enter the required PEM Passphrase if PEM is choosen.
	Specify the Distinguished Name and Attribute Fields for the CSR. Click [Create]. A notification is shown that the CSR is created successfully. Click the [Click here to view] link to view the content of the request.
Make sure you double check the Common Name as this is the DNS name used to connect to the website. Also note down the chosen challenge password as you will need to provide this password later on.
	Click on [View] to copy/paste the Certificate Request or save it to a text file (on your local machine).
	Click [Close].

As some prefer to use the Internet Information Service console to generate the Certificate Signing Request (which automatically generates a private key), I have included the instructions in this blogpost as well

Screens	Actions
	Open the Internet Information Services (IIS) Manager and select the Server Name in the left pane.
	Double click on Server Certificates
	Click [Create Certificate Request…] in the Action Pane.
	Specify the Distinguished Name properties and click [Next].
	Select the appropriate Cryptographic service provider and bit length and click [Next].
	Specify a File Name for the CSR and click [Finish].
You can check for pending requests in the Certificates MMC for the Local Computer. The certificate requests are stored in the Certificate Enrollment Requests folder.
	Checking the Certificate Enrollment Requests.

If all goes well, you will receive your certificate in a PKCS#12 (certificate store) format from your Certificate Authority after you requested your certificate and provided them with the CSR. Even though Citrix offers a great support article (CTX136444) on the import of PKCS#12 file into the NetScaler, I did include the instructions in this blogpost to offer a complete reference. The NetScaler works best with PEM (Base64-encoded) certificate and needs to convert a PKCS#12 certificate store into a PEM certificate store format.

Screens	Actions
	Log onto the management console of the NetScaler. Expand Traffic Management in the left pane and select the SSL node.
	In the right pane click on [Import PKCS#12] in the Tools section.
	Enter a name for the Output File Name (.pem file). Browse to the location of the PKCS#12 file on your local system and provide the import password. Enter a PEM Passphrase and click on [OK].
The import Password is the password of the pfx file, usually provided by the Certificate Authority together with the certificate. The PEM Passphrase is the passphrase for the PEM certificate file the NetScaler creates as part of the file conversion it performs for the PKCS#12 file.
	The PEM file is created on the appliance.
If you view the PEM file, you’ll notice that the private key as well as the certificates are included in the file.

If a PEM (Base64-encoded) file is provided, the previous import step is not required and the certificate can be imported right away on the NetScaler using a different wizard.

Screens	Actions
	Log onto the management console of the NetScaler. Expand Traffic Management in the left pane and expand the SSL node. Select the Certificates node.
	Click in the right pane on [Install].
	Specify a Certificate-Key Pair Name to uniquely identify the certificate. Browse for the PEM certificate store. As the PEM file also contains the private key, you can use the same file as the Key File Name Select the PEM Certificate Format and enter the PEM Passphrase (of the PEM certificate store) in the Password field. Select whether an expire notification should be given, enter the Notification period and click [Install].
	The certificate is shown in the list of available certificates of the the SSL Certificates node.

Root and intermediate certificates can usually be downloaded from the Certificate Authority as a single certificate PEM or DER encoded file. These files are usually not password protected.
You can import the intermediate and root CA certificates with the following steps:

Screens	Actions
	Log onto the management console of the NetScaler. Expand Traffic Management in the left pane and expand the SSL node. Select the Certificates node.
	Click on [Install].
	Specify a Certificate-Key Pair Name to uniquely identify the certificate. Browse on the Local system for the downloaded Intermediate or Root CA certificate. If the certificate is a PEM Base64-encoded file select the PEM Certificate Format and leave the Password field empty. If the certificate is a DER-encoded file select the DER Certificate Format (no password is required). Select whether an expire notification should be given, enter the Notification period and click [Install].   The certificate will be visible in the list of available certificates of the SSL Certificate node.

To ensure no SSL Error 61 messages are shown when a user connects to a XenApp or XenDesktop site through the NetScaler, you will need to make sure that all certificates in the certificate chain (or certificate path) are available on the NetScaler and are linked correctly. To create a certificate path on the NetScaler you need to link the server certificate to the Intermediate CA certificate that issued it and the Intermediate CA certificate to the Root CA certificate that issued it. So each certificate needs to be linked to the Certificate Authority that issued the certificate to create the entire certificate chain from server certificate to root CA (and all Intermediate certificates in between). Here are the steps to link certificates on the NetScaler to create the certificate chain:

Screens	Actions
	Log onto the management console of the NetScaler. Expand Traffic Management in the left pane and expand the SSL node. Select the Certificates node.
	Select the Server certificate and select the Link action from the Action selectbox.
	Select the Intermediate Certificate that is used to sign the Server certificate as the CA Certificate Name and click on [OK].
	Repeat the same steps to link the Root CA certificate to the Intermediate Certificate to ensure the entire certificate chain is created.
You can check whether the certificates are linked correctly by selecting the Intermediate Certificate and selecting the Cert Links action from the Action selectbox.

After all the required actions are done to request the certificate, import the server, intermediate and root certificates and link them together to create the certificate chain we can finally assign (or bind) the certificate to the Virtual Server on the NetScaler.
As the NetScaler has different Virtual Server types, I’ve used a Gateway Virtual Server as an example. Even when a certificate is already assigned to the Virtual Server, the steps to perform will be the same.

Screens	Actions
	Log onto the management console of the NetScaler. Expand NetScaler Gateway in the left pane and select the Virtual Servers node.
	In the right pane select the correct Virtual Server and click on [Edit].
	In the Certificates section click on the [>] icon after the (first) Server Certificate line.
	Click on [Add Binding] to select a server certificate from the list of available certificates.
	Click on [>] in the Select Server Certificate selectbox to view a list of all available certificates.
	select the SSL certificate from the list and click on [OK].
	Click on [Bind].
	Click on [Done] to save the configuration changes for the Virtual Server.
	Open the virtual server website by browsing to the url with a web browser (I used Internet Explorer in the example) and view the certificate properties. If all went well the certificate does not show any errors (the cert links for the certificate chain are in place) and the right certificate information is shown.

Esther Barthel

Solutions Architect at cognition IT

Esther has been working in different roles and functions as an IT consultant ever since she finished her Masters degree in Computer Science in 1997. She has worked as a web developer, database administrator, and server administrator until she discovered how Server-Based Computing ( SBC ) combined servers, desktops, and user experience in one solution. Esther has been specializing in virtualization solutions such as SBC, VDI, application, and server virtualization for over eight years now and is currently working as a Senior Consultant at PepperByte, where she designs and implements Citrix® solutions for both small-business and large-enterprise infrastructures scaling from 100 to 15,000 users.
In january 2014 her first book Citrix XenApp 6.5 Expert Cookbook was published by Packt Publishing.

Esther is awarded as a Citrix Technology Professional (CTP) from 2015 - 2017.
Esther is awarded as a Microsoft Most Valuable Professional (MVP) in 2017.

Esther is a Citrix Certified Expert – Virtualization (CCE-V), Citrix Certified Professional – Mobility (CCP-M), Citrix Certified Professional – Networking (CCP-N) and RES Software Certified Professional (RCP).