In this post we are going to be looking at setting up Client Authentication on your Citrix NetScaler using self assigned Windows certificates and a Windows CA.
Client authentication involves a client certificate which is a type of digital certificate that can be used by client systems to make authenticated requests to a remote server. Client certificates play a key role in many mutual authentication designs, providing strong assurances of a requester’s identity.
This setup will involve configuring your NetScaler and Storefront for client authentication and the creation of the client certificate. This client certificate will then need to be installed on all requesting client computers, otherwise access to the NetScaler login page will be forbidden.
Additionally we will also look at an SSL error that is closely tied to this setup. The error involves users getting a certificate authentication prompt when trying to log into their apps or desktop. [ Error: “Unable to Launch Application. Cannot connect to the Citrix XenApp Server. Socket operation on non-socket.” ]
Video showcasing the result of this setup –
Firstly without the client certificate and then after installing it.
(Due to OBS recording my browser rather than my display, the successful remote connection through storefront won’t be displayed in the video, in addition to me selecting the certificate from my file directory during the import process into Firefox)
First step – Create the Client Certificate
In your Citrix netscaler web gui, navigate to the Client Certificate Wizard. Do this by going to the Configuration tab, then selecting Traffic Management in the left side bar. Followed by SSL and then Client Certificate Wizard.
Under the Create Key drop down, enter the following details. You can name the keyfile whatever you fancy and remember to give the key a PEM passphrase for security.
After that follow on with the setup and create your CSR –
The common name is my public IP considering I am not using DNS records for this setup. If you were using a domain name as your landing address you would put that in there. (i.e microhard.local).
Use the same PEM passphrase you setup for the key you created previously.
Now the setup page should look something like this after you have created both the Key and the CSR file.
The next step in the SSL Certificate Wizard is to create the certificate. Do not do this. Instead, copy the CSR file from the /flash/nsconfig/ssl/ directory on the NetScaler appliance to a Windows computer/server for the next step.
As shown below you can use the utility WinSCP to transfer the certificate of the NetScaler file directory.
[Optional] – To request a certificate from your Domain CA you are going to need to use a domain account to access the certserv web gui. This part of the process is shown below as it’s required to create the certificate. The way I prefer to do it is to create a new domain account with heavy restrictions, no domain admin for instance. This account will then be used in the process of creating the certificate. (Don’t worry, anyone can use the certificate regardless of whether they are that new account or not. They just need the certificate installed on their workstation.
In this example I am going to create an account called CitrixAuth
Creating the Certificate using your Windows Domain CA
Now that you have the CSR off your NetScaler and on your workstation.
Navigate to Microsoft Active Directory Certificate Services.
Login using an account preferably with minimal access for security reasons. I’m using the basic account I created above which doesn’t have any admin rights.
Click Request a certificate then Advanced Certificate request.
Open the CSR saved to your computer using Notepad. Copy and paste the contents into the text box under Saved Request. In Certificate Template, select User and click Submit.
Click the Base 64 encoded radio button then press Download certificate.
Install the Microsoft-generated certificate
Return to the NetScaler SSL Server Certificate Wizard, skip step 3, and go to step 4 to install the certificate. Fill in the fields making sure to upload your saved Microsoft certificate on your computer under Certificate File Name and your RSA key you create earlier under the Key File Name.
When the certificate uploads, a prompt appears for the name and password of the Key File that you created earlier. Once everything is filled in click Create and then click Done.
You should now see your client certificate under Traffic Management > SSL > Client Certificates.
Next step is to enabled client authentication on your NectScalers Virtual Gateway server
You do this by navigating to the Configuration Tab, then proceed to the NetScaler Gateway followed by Virtual Servers.
Click on your setup Virtual Server and go into SSL Parameters drop down. Proceed to tick the Client Authentication radio button and then select Mandatory on the drop down. Then press OK. Followed by Done at the bottom to saved changes.
The Problem – Client Certificate Authentication Prompt Appears while Launching Application through NetScaler Gateway Integrated with StoreFront.
At this point you would assume everything has now been configured correctly on the NetScaler end as per Critix recommendations.
However, as of writing this post most people will run into a problem later on whereas a client (with the correct certificate installed) will be able to connect to the NetScaler but won’t be able to connect to their remote session through StoreFront. What happens is upon opening a Storefront desktop or application, they will receive a certificate prompt and ultimately an SSL error.
The Error: ‘ The connection to ‘Storefront Desktop’ failed with status (Socket operation on non-socket (Socket Error 10038)) ‘
This can be shown below.
The Solution – Create another Gateway Virtual Server on a different port to the original where client authentication is unchecked (also works on a differnet IP).
The problem appears due to the client attempting to do an additional SSL handshake with the same NetScaler virtual server (because of the SSLProxy HOST defined in the ICA file) upon the user attempting to open a application or desktop.
The goal is to get around this problem is to make it so the SSL Proxy Host defined in the ICA file, points to your dummy virtual server where client authentication is unchecked, thus no additional SSL handshake is required.
Creating the Dummy Gateway –
As shown in the below screenshot, I have created another NetScaler Gateway, by going through the Create New Gateway wizard found under the XenApp and XenDesktop tab on the left on your NetScaler web GUI .
It has the same server certificate file, points to the same Storefront and authenticates using the same domain controller. The only difference is this dummy virtual server is on port 4300 as apposed to 443 which is the port set on my main virtual server.
(I used a different IP for my dummy server in this example. Citrix specifies using the same for both your Gateway virtual servers)
After completing the Gateway setup you should now see your dummy NetScaler Gateway Virtual Server as well as your original ones.
Nothing to specific for this solution needs to be setup on your dummy Gateway server settings wise. It should mimic the settings of your original Gateway Server, just without Client Authentication being checked (it will be unchecked by default). Ensure that everything vital is working such the connection to your Secure Ticket Authority Server.
Changing your Storefront Settings to reflect your NetScaler changes –
Now your dummy Gateway Server is up and running. You need to change your Storefront NetScaler Gateway settings.
On StoreFront go to Manage NetScaler Gateway
Now make sure the NetScaler Gateway URL under General Settings contains both the FQDN (or IP in my case) and the port of your dummy Gateway Server
Additionally under Authentication Settings, edit the Callback URL to also contain the port number of your dummy virtual server.
Exporting the Client Certificate of the NetScaler device in PKCS12 format
Now your Storefront has the correct settings and your NetScaler is setup correctly. It’s time to get your Client Certificate in a format that web browsers will accept. We can do this by exporting the Client certificate of your NetScaler in PKCS12 format.
To do this all you need to do is go back into your NetScaler web gui. Click on the Configuration tab, then Traffic Management on left side. Follow this up by clicking SSL, then Export PKCS#12 under Tools.
Fill in the correct details by choosing a file name and then pointing the export wizard to your Client Certificate and the key used to create it.
Create an export password so individuals can’t export this certificate off client workstations and then enter the PEM passphrase you used earlier during the process of creating the Client Certificate.
After clicking OK, use WinSCP again to go into your NetScaler file directory. Find your exported PKCS12 file and then copy it onto your workstation.
Thats it! – If everything is working on the NetScaler and Storefront side of things. All you need to do is install that certificate on a workstation requiring access. Then upon going to your NetScaler Gateway page, they will be prompted to use your installed certificate for the SSL handshake.
Any connecting workstation without your client certificate will receive a similar SSL connection error to the one below.
Other considerations –
In some cases Citrix points people to the use of port 4343 for their dummy gateway server, whilst also mentioning it can be any port other than port 443. I would advise against this as you may find it causes remote connections to drop randomly.