For on-premises UpGuard Core appliances, having a valid SSL certificate not only allows your users to browse and use the app securely, but also allows connection managers to be able to communicate robustly. This guide outlines how to create the correct certificate and key files for an UpGuard Account Manager to install on your appliance.

Outline

To install a valid SSL certificate on your UpGuard Core appliance, an UpGuard Engineer requires a certificate (crt) and private key file (key). This guide will walk you through the steps to generate these files, namely:

  • How to create a valid Certificate Signing Request (CSR) that contains the correct Common Name and Subject Alternate Names (SAN) to make modern browsers happy.
  • How to turn the CSR into a CRT and key.
  • What UpGuard Engineers do with the CRT and key files to install the certificate.

Generating a CSR

In this guide, we are going to use the domain name upguard.example.com as the domain of your UpGuard Core appliance. We’re going to assume your company owns and manages its root domain at example.com.

First, create a configuration file called something like upguard.example.com.conf and fill out the contents to be similar to the example format below.

[req]
distinguished_name = req_distinguished_name
req_extensions = v3_req
prompt = no
[req_distinguished_name]
C = US
ST = CA
L = Mountain View
O = Example Company Name
OU = My Team Name
CN = upguard.example.com
[v3_req]
keyUsage = keyEncipherment, dataEncipherment
extendedKeyUsage = serverAuth
subjectAltName = @alt_names
[alt_names]
DNS.1 = upguard.example.com

The main components you will need to set in this file are:

  • C: This is the country code for your organization. For a full list of country codes use your favorite search engine to find "SSL certificate country codes".
  • ST: This is the state or province for your organization.
  • L: This is the city or suburb of your organization.
  • O: This is the name of your organization.
  • OU: This is the organizational unit or team within your company.
  • CN: This is the common name or hostname associated with the certificate. This must match the hostname, for example upguard.example.com.
  • DNS.1: This is where SAN domains are listed. Here, if we're only associating the one domain with this certificate we only need to set one DNS.x entry.

Save and close the file.

Run the following command to generate the CSR and key files.

openssl req -new -out upguard.csr -newkey rsa:2048 -nodes -sha256 -keyout upguard.key -config upguard.example.com.conf

Then run the following command to verify the Common Name (CN) and SAN values are correct:

openssl req -text -noout -verify -in upguard.csr

You should now have both the upguard.csr and upguard.key files available.

Generating a CRT

Your company or hosting provider should provide you with a mechanism to convert a CSR and key into a valid CRT. Please ask your UpGuard Technical Account Manager for any assistance you might need in locating the correct team or tool within your organization.

The output of this tool may also give you a series of CRT files which will reference your main domain (upguard.example.com) up through an optional intermediate level certificate (potentially something like example.com) to a root level CA. You should concatenate these crt files into a single file “local to root”. That is, if you have three crt files you can merge them into one like this:

$ ls
upguard.example.com.crt
example.com.crt
rootCA.crt
$ cat upguard.example.com.crt example.com.crt rootCA.crt > merged.crt

Have the files merged.crt and upguard.key ready for your UpGuard Technical Account Manager.

Installing the Certificate

Installation of the certificate must be completed by an UpGuard Engineer because:

  • it requires direct access into the appliance, and
  • we are able to follow a correct procedure of backing up any pre-existing files before applying the update and being able to roll back incase the certificate files are invalid.

Given a crt and key file, an UpGuard Engineer will upload the files to the appliance and install the certificate and key. They will then monitor the update and test that the certificate installation was completed successfully.

What Next?

For other tips on keeping your UpGuard Core appliance healthy, please visit our guide on Appliance Maintenance.

Tags: