Connecting Insite to Intermapper using SSL

Overview

This document describes how to connect an Insite Server to an Intermapper Server using TLS/SSL protocol.

The key to achieving this connection to be sure that the "Common Name" in the certificate matches the domain name (or IP address) of the server you are connecting to.

This document describes how to do the following:

  1. Create a self-signed certificate.
  2. Import the certificate into Intermapper and Insite.
  3. Create a connection from Insite to Intermapper.

Creating a Signed Certificate

Use the following steps to create your signed certificate and prepare it for use with Intermapper and Insite.

NOTE: These steps can be used with either Windows or Linux systems. The examples below are for Windows

1. Open command window.

NOTE: For Windows users, be sure to open the window as an administrator.

2. Check your OpenSSL configuration.

From the command window, enter:

Windows:
where openssl
Linux:
which openssl

If you don't get a response containing a path to the OpenSSL program, check to make sure one exists somewhere on your system. For Windows users, CygWin, a Linux-like command line interface, includes openssl.

3. Determine your Java path.

A Java Runtime Environment (JRE) is installed with Insite.

For Windows systems, the JRE is usually at:

C:\Program Files\Help Systems\HelpSystems Insite

For Linux, the JRE is probably at one of these two locations, depending on whether you installed Insite as root or as another user:

/opt/insite/jre
/home/USERNAME/insite/jre

You will use this information to import your certificate to one of Insite's Java keystores.

4. Create a certificates directory.

This is a working directly where you create your certificates. It is not used by any software but is a convenient place to work on your certificates and supporting files. In the following examples, the path is C:\mycert.

cd [path to your new certificates directory]
cd C:\mycert

5. Create an OpenSSL configuration file.

Creating a configuration file reduces the amount of information you have to type into the command window (and thus the possibility for error) when you create the certificate. The configuration information is pulled from the file when you use the commands below to create the certificate.

Create a text file called openssl.cnf.

Use the following information to guide you:

[req]
distinguished_name = req_distinguished_name
x509_extensions = v3_req
prompt = no
[req_distinguished_name]
C = US
ST = MN
L = MyTown
O = MyCompany
OU = MyOU
CN = MyLocalDomain.local
[v3_req]
keyUsage = keyEncipherment, dataEncipherment, digitalSignature, nonRepudiation
extendedKeyUsage = serverAuth
subjectAltName = @alt_names
[alt_names]
DNS.1 = MyLocalDomain.local
		
NOTE: The above example does not use an IP address, but rather a local domain.
  • Of the above, the Common Name (CN) is the most important. This must match the destination URL in order for the connection to work.
  • If you are already part of a domain, you can use it.
  • If you are not, and want to use a domain in Windows, you need to add it to the Hosts file, located at:
    C:\Windows\System32\Drivers\etc\hosts
    Our testing shows that using the localhost IP address (127.0.0.1) works well. You should be able to ping the domain name and get a result.
  • If the machine you are running the server on has a static IP address, you can use that in place of the CN (Common Name) and the DNS entry.
  • There are many configuration options, including using multiple domains and addresses. These are beyond the scope of this topic.
  • The settings in the openssl.cnf file as described above have been tested, and should work on a machine that is not part of a domain. The URLs described below should also work.
  • The settings above have also been tested with the domain replaced with a static IP.

6. Create a PEM file.

This contains a certificate/key pair that you will use in Intermapper, Insite, and your browser. The file format is plain text.

openssl.exe req -x509 -nodes -days 730 -newkey rsa:2048 -keyout cert.pem -out cert.pem -config openssl.cnf

7. Create a PFX file.

This file is compatible with your browser, and is password-protected. The file format is binary.

openssl pkcs12  -in cert.pem -export -out cert.pfx  -passout pass:mypassword
NOTE: In this topic, the PFX file is created only for the purpose of verifying that you can connect to Intermapper server using the certificate you create.

8. Create a CRT file.

This step creates a file that contains only the certificate, not the private key. The file format is plain text.

  1. Open cert.pem with a text editor.
  2. Save the file as cert.crt.
  3. Delete the PRIVATE KEY section of file and save again.

You now have, in addition to your openssl.cnf file,

  • a PEM file - text format, contains both the self-signed certificate and the private key.
  • a PFX file - contains a binary formatted, password-protected version of the certificate, including a private key, suitable for importing into a browser.
  • a CRT file - text format, contains only the certificate, not the private key.

Using Your Signed Certificate

1. Import the Certificate into Intermapper.

Use the Upload Certificate... button on the SSL Certificate panel, available from the Server Settings window, to upload a signed certificate to the Intermapper server.

You can paste the contents of the PEM file into the box, or you can browse to the PEM file and upload it.

Once the certificate is uploaded, stop and restart the Intermapper server.

3. Import the Certificate into Your Browser.

How you import the certificate depends a lot on which browser you have. It is an advanced setting.

In Chrome, use the following steps:

  1. Go to Settings > Advanced > Privacy and security.
  2. Click Manage certificates. The Certificates window opens with a series of keystore tabs, each containing a set of certificates in a particular keystore.
  3. Click Import... The Certificate Import Wizard Welcome page opens.
  4. Click Next. The File to Import page opens.
  5. Click Browse... A standard File Open dialog appears.
  6. Navigate to your certificate working directory (C:\mycert in these instructions).
  7. In the File Type dropdown, choose Personal Information Exchange as the file type. The PFX file you just created appears.
  8. Double-click the file or select it and click Open. A Private key protection window appears.
  9. Enter the password you specified in step 7 of the previous section and click Next. The Certificate Store page appears.
  10. Click Browse... and choose the Trusted Root Certification Authorities store, (To use the certificate with Chrome, you must place it in this store.) then click Next. The Completing the Certificate Import Wizard page appears.
  11. Click Finish. A Security Warning page appears, asking if you want to continue. Click Yes to install the certificate.
  12. Verify your connection as described below.
NOTE: This step is strictly for troubleshooting, and is not required for operation of Insite with Intermapper.

4. Verify your connection.

  1. From the Web Server Panel of the Intermapper Server settings window, click to select the Use a secure protocol (SSL v3/TLS) check box. The port changes from 80 to 443, and the URL changes from HTTP to HTTPS.
  2. Quit and restart your browser.
  3. Enter the domain name from the Common Name entry of your openssl.cnf file, and use port 443:
    https://MyLocalDomain.local:443

    If the certificate is properly installed, your browser launches and opens the Intermapper web server's home page without complaint. This proves that you can connect to the Intermapper server using your self-signed certificate.

2. Import the Certificate into Insite.

Use Java's keytool program to import the certificate into Java.

NOTE: To connect Insite to Intermapper, the certificate must be imported into the cacerts keystore. The default password of the cacerts keystore is changeit.
  1. Change your working directory and import the certificate into Insite's Java cacerts keystore as shown below.

    cd C:\Program Files\Help Systems\HelpSystems Insite\jvm\lib\security
    ..\..\bin\keytool -import -trustcacerts -file C:\mycert\cert.crt -alias mycert -keystore cacerts -storepass changeit
  2. Enter "yes" when prompted to indicate you trust the certificate.
  3. Stop and restart the Insite Server service.

3. Create a Product Connection

Once the certificate is in place in both Intermapper and Insite, you are ready to create a product connection.

Connect to Insite using the Common Name value from your openssl.cnf file.

Create a new product connection as described in the Insite help.

Make sure to use the following settings:

  • Connection type - Intermapper
  • Address - the value of the Common Name as contained in the certificate.
  • Port - 443
  • User Name and Password - enter valid user name and password for an Intermapper user.
  • Use TLS - set to on.

If the certificates are in place, the Intermapper server's Web Server is running in TLS mode, and the Address matches the Common Name, the connection should appear in the connection list with a green checkmark.


Still have questions? We can help. Submit a case to Technical Support.

Last Modified On: September 30, 2019