Enable HTTPS

HTTPs support in MyConnection Server (MCS) requires version MCS 10.1a or above

As a best practice this tutorial documents 4 steps to create the MCS certificate file using the Windows platform. The certificate file can be transferred and used with MCS on both Linux and Windows platforms.

We recommend performing these steps on Windows even if MCS is installed on Linux.

Passwords used throughout the process must match and only contain letters and numbers, no special characters.

The 4 steps to enabling HTTPs/SSL in MCS are as follows:

• Create a combined SSL certificate that was provided by a certificate authority for use with MCS.
• Convert the Certificate created in step 1 to an OpenSSL PKCS file.
• Convert the PKS file into a Java Key Store (.jks) file for use by MyConnection Server.
• Configure MCS to locate and use the .jks file.

Notes:

Passwords used throughout the process must match and only contain letters and numbers, no special characters.

Files created during the certificate build steps have been color coded for clarity of use.

Support. If you need help with the SSL certificate application process review the troubleshooting section or send us an email us.

A valid SSL certificate provided by the issuing certificate authority is required for this step. The certificate must consist of 2 files, example yourdomain.com.crt and intermediateCA.crt.

NOTE: Some certificate providers will provide a .PEM file option, for example yourdomain.com.pem. If you have a .PEM file then skip to Step 2.

The two certificate (.crt) files need to be combined together to create a single file as follows:

• Create and name a folder on the Windows desktop or other suitable location.
• Place the two certificate files to be combined in the named folder.
• Open a Windows command prompt and navigate to the named folder directory
• Enter the command: type yourdomain.com.crt IntermediateCA.crt › certs.txt (see example below) to create the combined file.
  
  
• Leave the command window open for continued use in step 2 below

This step requires the OpenSSL package for Windows (Note: Scroll down to the Download Win32 OpenSSL section for download links. This is a third party OpenSSL resource that we've found the most reliable but is subject to change) in order to convert the combined certificate file to the OpenSSL PKCS file format.

• If not already installed, download and install the full OpenSSL installer appropriate for the processor architecture required (32 bit or 64 bit)..
• Once installed, locate the bin directory in the install folder. For 64bit platforms this should be drive:\OpenSSL-Win64\bin.
• Add the bin directory path to the Windows PATH environment variable to allow OpenSSL to process from the open command prompt window.
• Enter the command line:

  CRT method: openssl pkcs12 -export -inkey yourdomain.com.key -in certs.txt -out certs.pkcs12 (see example below).

  PEM method: openssl pkcs12 -export -inkey yourdomain.com.key -in yourdomain.com.pem -out certs.pkcs12

  

• When the password prompt appears. Enter a strong alphanumeric password (8 to 16 characters) and continue. Note, this password will be required in Step 3. below
• Verify that the OpenSSL certs.pkcs12 file will be created.
• Leave the command window open for continued use in step 3 below.

This step requires the Oracle Java keytool utility.

• If not already installed download and install the Oracle Java JDK.
• Add the JDK bin directory path to the Windows PATH environment variable.
• Enter the command line keytool -importkeystore -srckeystore certs.pkcs12 -srcstoretype PKCS12 -destkeystore certs.jks -deststoretype JKS (See example below)

V:\SSL Certs>keytool -importkeystore -srckeystore certs.pkcs12 -srcstoretype PKCS12 -destkeystore certs.jks -deststoretype JKS
Enter destination keystore password:
Re-enter new password:
Enter source keystore password:
Entry for alias 1 successfully imported.
Import command completed:  1 entries successfully imported, 0 entries failed or cancelled

• When requested, enter a strong alphanumeric for the destination password (8 to 16 characters) and re-enter the same password for confirmation when prompted.
• When prompted for the keystore password enter the same password used when creating the certs.pkcs12 file in Step 2, item 5. If these do not match the certificate will be denied at run time.
• The Java certs.jks file should have been created for use in Step 4.

• Navigate to the \MCS root directory\data\ directory on the system where MCS has been installed. The Key is valid to be used on Linux or Windows platforms.
• For first time implementation rename the example-https.ini file to https.ini.
• Copy the certs.jks file created in step 3 above to the \MCS root installation directory\data\ directory.
• Edit the https.ini file and (1) amend the SSLKeyStoreFileName setting to reference the certs.jks file name, and (2) amend the SSLPassword setting to reference the password that was enter in step 2 item 5.
  
• The certificate configuration process is now complete.

  MCS should be stopped and restarted to enable the SSL certificate. If a restart does not enable HTTPS then there may be an issue with the cert or JKS, please review the troubleshooting section below.

  Once enabled, only HTTPs traffic will be authorized and any user login requests initiated over HTTP will be automatically redirected to HTTPS. Note, port 80 is still required for redirects and support of high performance MCS hardware and software satellites which will continue to be authorized to ensure test accuracy.

• Passwords used throughout the process must match exactly and contain only letters and numbers—special characters are not allowed.
• Verify that the password specified in the HTTPS.ini file matches the one used for the certificate JKS file.
• Ensure that the JKS filename specified in HTTPS.ini is correct and that the file exists in the /MCS Root/data directory.
• Confirm that the installed Oracle Java JDK is the latest stable release. Issues have been reported with early access (EA) and release candidate (RC) versions.

The first step to detecting the JDK type installed is to run the command below.

java --version

If this does not explicity state EA or RC then check the package manager.

Debian/Ubuntu:

apt list --installed | grep openjdk

Red Hat/Fedora:

dnf list installed | grep java

Arch Linux:

pacman -Q | grep jdk

Some Java distributions (like OpenJDK) store version details in /usr/lib/jvm/

ls -l /usr/lib/jvm/

• Check the MCS console log located in /MCS Root/logs/. If MCS encounters an issue verifying the certificate, details will be recorded there.