Configuring MettleCI Workbench to use HTTPS with an existing certificate

In https://datamigrators.atlassian.net/wiki/spaces/MCIDOC/pages/458556297 we describe how to create and install a self signed certificate. However, some organizations prefer use of a certificate that has been signed by a CA (or can trace signatures to a root certificate signed by a CA). There are many ways to create or obtain such a certificate, and discussion of those ways is out of scope for this documentation. Consulting the OpenSSL documentation may be helpful if you are tasked with doing it yourself. Consulting with system administrators, network administrators, or the security team may be required to determine your organizational process for requesting a certificate signed by a CA.

Some key points about certificates

• Certificates come in many formats, which may or may not be interconvertible with the tools available to you. If you are requesting or creating one, using the PKCS#12 format will be convenient, as that is what is used in the enabling HTTPS examples. The file may be supplied or generated with a .pfx or .p12 file suffix, either will work.

• You will need the keystore password for the certificate. This is stored in the config.ymlfile, either directly, or via indirection to a secrets repository

• Checking the certificate to ensure it’s been signed, or that it is chained to a CA signed root before trying to use it may help you avoid problems. You can examine created or provided certificates by using keytoolwhich will be available with your OpenJDK installation. Consult the keytool manpage documentation for details.

• Certificates may be specific to a particular form of the machine name. They may not give you a secure connection if the numeric form (123.34.45.56:8443) or short form (only the machine name without the domain name) is used.

Once you have created or had one provided to you, and it is on the server where MettleCI Workbench will be running, the installation process is similar to that given in the referenced page, with some differences as noted

• Enable HTTPS support in workbench. See https://datamigrators.atlassian.net/wiki/spaces/MCIDOC/pages/458556297/Configuring+MettleCI+Workbench+to+use+HTTPS#Enabling-HTTPS-support

  • You will need the absolute path to where the certificate is, the name can be anything but we suggest a meaningful name such as workbenchEntrustSigned.p12 (or whatever CA may apply in your case)

  • You will also need the keystore password. it is possible to not have one at all, although this is not a good practice, and this may require an exception in the process you used to obtain your certificate.

  • MettleCI typically uses the same certificate for both the keystore and the truststore so the information in the applicationConnectors:section will be duplicated for the two stores. If admin connectors are in use and you also want the adminConnectors: to be enabled using the same keystore and truststore configuration, duplicate these entries again, giving you a total of 4 references to the certificate and password.

• After you restart the server the instructions https://datamigrators.atlassian.net/wiki/spaces/MCIDOC/pages/458556297/Configuring+MettleCI+Workbench+to+use+HTTPS#Trusting-your-certificate explain how to import the certificate into browsers as necessary. However, if you have a certificate signed by a CA, or traceable to a root signed by a CA, you should not need to import things.

Once you have changed your configuration to use the new certificate, and you have restarted workbench successfully (if it doesn’t start, check your mci.log for errors) you can test the certificate by pointing your browser to the https URL you’ve established, and then click on the left “padlock” icon. For a valid certificate it looks something like this: (Windows using Chrome, uses a grey closed padlock, but other OS and browser combinations may present information differently) rather than the “not secure” appearance show in the Trusting your Certificate section.

Open

Result of clicking on on the padlock at left of the URL bar

To see more details, click on “connection is secure” and you should see something analogous to this

Open

Connection security details

With these tips in mind you can continue the process outlined in the documentation section.