Installing an Active-Directory-Signed TLS Certificate for Variphy in a Windows Environment

This tutorial will walk you through requesting, signing, and installing an Active-Directory-Certificate-Services-signed TLS certificate for the Variphy Insight in a Windows environment.  Using a certificate signed by your organization’s Active Directory server should allow you to use the Variphy Insight web interface over HTTPS (“HTTP Secure”), without the pesky browser warning messages:

If your organization uses Active Directory Certificate Services (or a similar Public Key Infrastructure system), you can create a certificate that is signed by your organization’s root certificate.  Since this root certificate can then be added (or already has been added) to your organization’s workstations by your system administrators, the above browser message should instead look like this:

Configuration Steps:

1. Open File Explorer and make rename of the original keystore file
   • The file is named keystore.pfx. Rename it to keystore.pfx.copy
   • The location of the file will depend on where Variphy was installed, a common path is C:\Program Files\Variphy Insight\app\tomcat
2. Open CMD as an Administrator and navigate to the \Variphy Insight\jre\bin folder.
3. To create a new keystore make a copy and run either of the following commands, update any arguments per the instructions below and run in CMD

Multi-line (easier to read)

keytool.exe ^
-genkeypair ^
-dname "CN=sw-dev-ova-test-03" ^
-alias tomcat ^
-storetype pkcs12 ^
-keyalg RSA ^
-keysize 2048 ^
-sigalg SHA256withRSA ^
-validity 3650 ^
-storepass changeit ^
-keystore "C:\Program Files\Variphy Insight\app\tomcat\keystore.pfx"

One-line (not as easy to read)

keytool.exe -genkeypair -dname "CN=sw-dev-ova-test-03" -alias tomcat -storetype pkcs12 -keyalg RSA -keysize 2048 -sigalg SHA256withRSA -validity 3650 -storepass changeit -keystore "C:\Program Files\Variphy Insight\app\tomcat\keystore.pfx"

• keyool.exe – runs the bundled keytool application
• -genkeypair – tells keytool to create a new key pair
• -dname – tells keytool the distinguished name to use for the new keypair. You should change this value (after CN=) to reflect the fully qualified domain name of your Variphy server.
• -alias – specifies the name of the alias under which the public/private key will be stored in the keystore.
• -storetype – specifies the type of keystore we will use. We’re specifying PKCS#12 here.
• -keyalg – specifies the name of the algorithm to use for the key.  We’re specifying RSA here.
• -keysize – specifies the size of the key.  We’re specifying a key size of 2048 bits.
• -sigalg – specifies which algorithm to use for the certificate signature.  We’re specifying SHA-256 here.
• -validity – specifies the number of days that the key pair will be valid.  We’re specifying 10 years here.
• -storepass – specifies the password to use to restrict access to the keystore.  The default value is changeit.  You can change this password to something else.
• -keystore – specifies where we will put our new keystore.  If Variphy is installed on a different drive or location update the path. This should be the path from step 1.

4. Run the command below to check the newly created keystore. If you specified a value other than changeit for the password, use the same password in the command.

Multi-line (easier to read)

keytool.exe ^
-list ^
-v ^
-storepass changeit ^
-storetype PKCS12 ^
-keystore "C:\Program Files\Variphy Insight\app\tomcat\keystore.pfx"

One -line (not as easy to read)

keytool.exe -list -v -storepass changeit -storetype PKCS12 -keystore "C:\Program Files\Variphy Insight\app\tomcat\keystore.pfx"

• keytool.exe – runs the bundled keytool application
• -list – tells keytool we want to list the entries
• -v – tells keytool to give verbose output
• -storepass – specifies the keystore password. If you specified a value other than changeit for the password in Step 3, use the same password here as well.
• -storetype – tells keystore that this is a PKCS#12 keystore
• -keystore – pecifies the keystore we are looking to read.

5. Create a Certificate Signing Request (CSR). Run the following command in CMD from the \jre\bin folder. Make sure to change the options to fit your environment:

Multi-line (easier to read)

keytool.exe ^
-certreq ^
-dname "CN=sw-dev-ova-test-03, OU=Information Technology, O=Variphy Inc., L=San Francisco, ST=California, C=US" ^
-ext "SAN=dns:sw-dev-ova-test-03,IP:10.20.30.146" ^
-keyalg RSA ^
-alias tomcat ^
-file "C:\Program Files\Variphy Insight\csr.pem" ^
-storepass changeit ^
-keystore "C:\Program Files\Variphy Insight\app\tomcat\keystore.pfx"

One line (not as easy to read)

keytool.exe -certreq -dname "CN=sw-dev-ova-test-03, OU=Information Technology, O=Variphy Inc., L=San Francisco, ST=California, C=US" -ext "SAN=dns:sw-dev-ova-test-03,IP:10.20.30.146" -keyalg RSA -alias tomcat -file "C:\Program Files\Variphy Insight\csr.pem" -storepass changeit -keystore "C:\Program Files\Variphy Insight\app\tomcat\keystore.pfx"

• keytool.exe – runs the bundled keytool application
• -certreq – tells keytool that we are looking to create a certificate signing request
• -dname – tells keytool which distinguished name we want to use. You should change these values to match your environment. CN = Common Name – this should be the fully qualified domain name of the server
  • OU = Organizational Unit – specifies the division within an organization
  • O = Organization – corporation, limited partnership, university, or government agency registered with some authority at the national, state, or city level
  • L = City or Locality – usually denotes the city in which the organization is located
  • ST = State – U.S. or Canadian State or Province name
  • C = Country – the 2-character ISO format country code
• -ext – tells keytool we would like to add an extension to our CSR.  This is due to needing to specify a Subject Alternative Name (SAN) for this CSR.  In this tutorial, we are going to specify the fully qualified domain name of the server, as well as the server’s IP address.  The certificate you receive back from your CA should be valid for both the domain name and the IP address of the server.  Change these values to match your environment.After dns: you should put your server’s fully qualified domain name
  • After IP: you should put your server’s IP address
• -keyalg – specifies the name of the algorithm to use for the key.  We’re specifying RSA here.
• -alias – this argument specifies the name of the alias under which the public/private key can be found in the keystore.
• -file – tells keytool where to write the resulting CSR file.  The example uses C:\Program files\Variphy Insight/csr.pem
• -storepass – specifies the password to use for accessing the keystore. If you specified a value other than changeit for the password in Step 3, use the same password here as well.
• – keystore – specifies the keystore we want to use to create this CSR.

6. In CMD you can run the following command to list the Certificate Signing Request (CSR) Contents. You will need to be in the jre\bin folder.

Multi-line (easier to read)

keytool.exe ^
-printcertreq ^
-v ^
-file "C:\Program Files\Variphy Insight\csr.pem"

One line (not as easy to read)

keytool.exe -printcertreq -v -file "C:\Program Files\Variphy Insight\csr.pem"

• keytool.exe Run the keytool application
• -printcertreq – tells keytool that we want to print the certificate request contents
• -v – specifies verbose output
• -file – specifies where to find the CSR file

7. You can copy the Certificate Signing Request (CSR) file from the Variphy server to open on your local machine. If you used the path in the previous commands the file should be in the C:\Program Files\Variphy Insight folder. Or you can use a text editor like Notepad or Notepad++ to copy the contents of the CSR file to your clipboard

NOTE: Before you submit the certificate, it is recommended to confirm the contents in a free CSR viewer, such as https://www.entrust.net/ssl-technical/csr-viewer.cfm

8. Submit the Certificate Signing Request to your Certificate Authority.
   • At this point in the process, your organization’s Certificate Authority needs to review your CSR and respond with a signed public key certificate.  Your organization may have a person or group that handles this process for you.  You will just need to get the CSR to them.
   • Alternatively, if you can access your organization’s Active Directory Certificate Services site directly, navigate to it in a web browser.  The URL is usually of the form http://active-directory-server/certsrv/Click on the “Request a certificate” link

• From the next screen, click on ‘submit an advanced certificate request’ link

• Paste the CSR contents into the ‘Base-64-encoded certificate request’ text field on this screen.  Then, change ‘Certificate Template’ to ‘Web Server’.  Finally, click the ‘Submit >’ button.

• From the “Certificate Issued” screen, select ‘Base 64 encoded’ and click the ‘Download certificate chain’ link.  Your browser should download a ‘certnew.p7b’ file.

• Upload this file to your OVA server.

7. Next we’re going to import the signed public key certificate and chain into the keystore. Copy the signed public key certificate file to the “C:\Program Files\Variphy Insight” folder (or another folder of your choice). We’ll use “certnew.p7b” for our certificate file name in the example commands.
   • In CMD in the jre\bin folder run the multi-line or one-line command listed below. After executing the import command, you may see a prompt saying “... is not trusted. Install reply anyway? [no]: “
   • If you see this, type yes and press enter to continue.

Multi-line (easier to read)

keytool.exe ^
-import ^
-alias tomcat ^
-keystore "C:\Program Files\Variphy Insight\app\tomcat\keystore.pfx" ^
-storepass changeit ^
-file "C:\Program Files\Variphy Insight\certnew.p7b"

Single line (not as easy to read)

keytool.exe -import -alias tomcat -keystore "C:\Program Files\Variphy Insight\app\tomcat\keystore.pfx" -storepass changeit -file "C:\Program Files\Variphy Insight\certnew.p7b"

• keytool.exe – Runs the keytool application
• -list – tells keytool we want to list the entries
• -v – tells keytool to give verbose output
• -storepass – specifies the keystore password. If you specified a value other than changeit for the password in Step 3, use the same password here as well.
• -storetype – tells keystore that this is a PKCS#12 keystore
• -keystore – this argument specifies the keystore we are looking to read.

8. Before we restart Variphy Insight, let’s check the  C:\Variphy Insight\config/https_customizations.xml file.  If you have never changed this file and used changeit as the keystore password (as was done in this document), things should work just fine.  But just in case, let’s take a look.
   • Open the file in a text editor like Notepad or Notepad++
   • Note that keystoreFile (highlighted in the screenshot below) should be keystore.pfx (which represents C:\Program Files\Variphy Insight\app\tomcat\keystore.pfx as we’ve used in this document. Change this path if your environment is different)
   • Note that keystorePass (also highlighted in the screenshot below) is changeit (as we’ve used in this document). If you used a different keystore password in Step 3, then you will need to change the text after cerfiticatekeystorePass=" here.
   • If you need to make any edits to this file, do so now and save the file. If you copied the file off of the Variphy server make sure you upload it to to C:\Program Files\Variphy Insight\config (or a different path if Variphy is installed in another location). Make sure that the uploaded file is named https_customizations.xml.

9. Restart the Variphy service and check the HTTPS endpoint.
   1. Restart the service using the Services Manager or from CMD.
   2. Navigate to https://your-variphy-server:8443

Optional: Active Directory Root Certificate

• If your browser is now showing Variphy Insight as trusted then you are done with these steps. But if for some reason your browser is still showing a “This site cannot be trusted” message, then your workstation may not know about your Active Directory server’s root certificate. Your IT Administration team should know whether your workstation should already have access to the Active Directory server’s root certificate. The following steps will walk you through manually adding the Active Directory root certificate to the Firefox browser. Please note that this process will need to be repeated on each workstation and browser that does not have the Active Directory root certificate, and it is therefore strongly recommended that your IT Administration team handle adding the Active Directory root certificate to your organization’s workstations.

1. Download the Active Directory Root Certificate
   • Navigate to your organization’s Active Directory server and click the ‘Download a CA certificate, certificate chain, or CRL’ link

On the ‘Download a CA Certificate, Certificate Chain, or CRL’ screen, select ‘Base 64’ for the ‘Encoding method’, and then click the ‘Download CA certificate chain’ link. This should download a certnew.p7b file to your workstation.

Add Active Directory Root Certificate to Firefox

• In Firefox, go to the menu in the upper right corner and click ‘Preferences’ (alternatively, open a new tab and enter ‘about:preferences’ into the URL bar)
• Next, click the ‘Privacy & Security’ tab.
• Scroll down to the bottom of the page and you should see a ‘Certificates’ section with a button that says ‘View Certificates’. Click the ‘View Certificates’ button.
• From Firefox’s ‘Certificate Manager’ dialog, click the ‘Import…’ button

• Select the newcert.p7b Active Directory CA chain file you downloaded from Active Directory a few steps earlier, and then click the ‘Open’ button.
• From the ‘Downloading Certificate’ dialog, select ‘Trust this CA to identify websites’ and click the ‘OK’ button.

At this point, your Active Directory root certificate should now be trusted by Firefox.