Manage the Security Certificate

Overview

The EchoSystem Server (ESS) uses SSL to secure the web browser session between the server and users accessing the server. To make the initial installation as simple as possible, ESS ships with a self-signed SSL certificate that enables this secure communication. There are several reasons why you might want to replace this SSL certificate with a more sophisticated one.

• You do not want users to see (and click past) the warning that most browsers display. This warning occurs because the browser cannot verify the identity of the certificate's owner. Typical warnings look similar to the ones shown below:

  

• You want to use a certificate authority (CA) of your own choosing or the CA that is required by your institution.

You can manage the certificate at any time, but you are most likely to make changes for one of the reasons listed below.

• The existing certificate has expired
• Your institution is working with a new CA
• You are installing a new ESS

Installing a new certificate consists of these phases:

1. Create the Certificate Signing Request (CSR), using either the request capability in the ESS or other means (such as making the request on the CA website). 
2. Install the security certificate. Install the certificate.
3. Restart the ESS.
   

You may also want to do these processes:

• Review existing certificates
• Remove a certificate

Create the Certificate Signing Request (CSR)

You can create a CSR using the ESS.

You may also create a CSR in other ways, perhaps via the CA website.  If you chose an alternate method (the "CSR Not Generated by ESS" method), you can skip this section and proceed to Install the Security Certificate with your otherwise generated certificate.

A CSR is a cryptographic document that is generated for a specific entity and submitted to a CA for signing. The CSR describes the identity associated with a particular fully-qualified domain name (FQDN). The result of generating and submitting a CSR is a signed certificate that web browsers will be able to recognize as valid for the server that presents it.

After you request the certificate, you will install the security certificate you receive.

You do not have to create a public key or private key yourself when making the CSR. That is done for you as part of this phase.

Procedure

1. Navigate to System > Certificates (the Show Certificates page).

   

2. Click Request Certificate.
3. You should see the Request Certificate page. Complete the fields.

   

4. Click Generate CSR.
5. Notice that the field to the right of the fields is now populated with your certificate request. The text below the field lists the file location of the CSR. The file location is underlined in the screenshot below.
   

   

6. Click Return.
7. Send the certificate request to your CA. You can:
   
   • Copy and paste the text from the block above into an email, or
   • Send the file to the CA
8. When you receive the security certificate from the CA, install the security certificate.

Install the Security Certificate

The procedure to install the security certificate differs, depending on these factors:

• Was the CSR generated by the ESS or by other means?
• Is a root certificate already installed?

The procedure below is divided into phases. Everyone must follow:

• Phase 1 - Enter the Intermediate Certificate Text
• Phase 2 - Do You Need to Install a Root Certificate?

Depending on the results of phase 2, you will continue with one of the following phases:

• Phase 3A - Root Certificate Already Installed
• Phase 3B - Install the Root Certificate

Phase 1 - Enter the Intermediate Certificate Text

1. Navigate to System > Certificates (the Show Certificates page).
   

   

2. Click Install Certificate.
3. Notice that the Install Certificate page is the first page of a wizard. The wizard guides you through the installation procedure.
4. Click the appropriate radio button, then click Next.
5. Click Next.
   
   • If you used the ESS to generate your CSR, see ESS-Generated CSR.
   • If you generated your Private Key and CSR outside of the ESS, see CSR Not Generated by ESS.

ESS-Generated CSR

1. You should see the page shown below.
   
   1. Open the email or text file received from the CA.
   2. Copy and paste the certificate text into the field, as shown below.

      

2. Click Next.

CSR Not Generated by ESS

1. You should see the page shown below.
   
   1. Browse to the PKCS12 file.
   2. Enter the password for the PKCS12 file.

      

2. Click Next.

Phase 2 - Do You Need to Install a Root Certificate?

If you see the page shown below, you already have a root certificate installed. The intermediate certificate has been installed successfully and you are almost done. Continue with Phase 3A - Root Certificate Already Installed. 

If you see the page shown below, you do not have a root certificate installed and must install one. Continue with Phase 3B - Install the Root Certificate.

Phase 3A - Root Certificate Already Installed

1. Notice the further instructions on this page.
   
2. Click Return to Certificates Page.
3. Restart the ESS.
   

   • The Jetty server has been reconfigured to work with the certificate

   • You will need to restart the ESS to allow the server to recognize the new certificate

Phase 3B - Install the Root Certificate

1. Read and understand the instructions on this page. Typically, you will need to install a root certificate that is linked to the intermediate certificate.
2. Copy and paste the root certificate text into the field, as shown below.

   

3. Click Install Certificate and Test Your Chain.
4. Look for a success message, as shown below.

   

5. Click Return to Certificates Page.
6. Restart the ESS (instructions below).
   

   • The Jetty server has been reconfigured to work with the certificate

   • You will need to restart the ESS to allow the server to recognize the new certificate

Restart the ESS

After you install the new certificate, restart the ESS service or daemon. This allows the server to recognize the new certificate.

Follow the instructions for your platform.

Restart ESS on Windows

1. From the Windows taskbar select Start > Programs > Administrative Tools > Services.
2. The Services dialog opens.
3. Select the EchoSystem Server service.
4. Click Restart. The ESS service restarts on your local computer.

Restart ESS on Linux

1. Open a terminal prompt.

2. Type the restart command. Be sure to include the space between the file name and the restart command.

   sudo /etc/init.d/echosystemserverd.sh restart

3. Notice the status messages showing that the service stops and starts.

Review Existing Certificates

1. Navigate to System > Certificates.

2. Hover over the certificate of interest.

   

3. Click details.
4. Notice that details about the certificate appear in the lower part of the page.

   

Remove a Certificate

Overview

You might remove a certificate when it expires or if your institution changes the CA it uses.

Procedure

1. Navigate to System > Certificates.
2. Select the certificate to be removed.
3. Click Remove.

   

4. Notice that the certificate is removed from the list.