How to add or renew an SSL certificate for OP5 Monitor

Monitor is initially set up with a so called self-signed SSL certificate. Browsing a website that is using a self-signed SSL certificate will yield an SSL error message in the web browser, upon which you must accept the "invalid" certificate to access the website anyway. Doing this will ensure the connection is encrypted, but no verification has been done to validate the identity of the server.

To get rid of these error messages, the SSL certificate for your Monitor instance must be properly set up, it must not have expired and it must have been signed by a trusted Certificate Authority (CA). Which Certificate Authorities are marked as "trusted" depends on your environment and configuration.

Prerequisites

To be able to complete this how-to you will need:

• to have decided which CA you want to use to sign your certificate. It can be an external CA, or an internal within your environment.
• to have set up a fully qualified domain name (FQDN) for your Monitor server (i.e. you access Monitor by a name resolvable in the DNS, not via the server's IP address).
• root command line access to the Monitor server (preferably via SSH).
• a web browser to verify the new certificate.

Create a Certificate Signing Request (CSR)

1. Log on to the Monitor server as root via SSH.
    
2. Begin creating a CSR based on the private key that is already installed, by executing the command below.
   

   openssl req -new -key /etc/pki/tls/private/localhost.key -out ~/localhost.csr

3. You will be asked a series of questions regarding the name and location of your organization. Fill out all the details, as many Certificate Authorities will reject your CSR if the fields are not properly filled out. All details should be valid, but should not contain sensitive information, since all details entered into this form can be viewed by anyone that is able to browse the Monitor web server.
   
   For example, the details can be entered like this:
   

   # openssl req -new -key /etc/pki/tls/private/localhost.key -out ~/localhost.csr
   Country Name (2 letter code) [GB]:SE
   State or Province Name (full name) [Berkshire]:Vastra Gotalands Lan
   Locality Name (eg, city) [Newbury]:Gothenburg
   Organization Name (eg, company) [My Company Ltd]:op5 AB
   Organizational Unit Name (eg, section) []:
   Common Name (eg, your name or your server's hostname) []:monitor.op5.com
   Email Address []:itadmin@op5.com
   
   Please enter the following 'extra' attributes to be sent with your certificate request
   A challenge password []:
   An optional company name []:

   It is very important to set the Common Name to the domain name used to browse your op5 Monitor server. For instance, if you access Monitor by browsing to:

   https://op5.your-company.com/

   ...then you should set the Common Name to:

   op5.your-company.com

   Sign the request

   Certificate Authority (CA) signing (recommended)

   1. Download the ~/localhost.csr file from your Monitor server.
   2. Provide your Certificate Authority with the CSR file, and follow their instructions to get hold of a certificate file.

   Self-signing (not recommended)

   In case you are just running a test environment for Monitor, you might not be interested in a certificate that is signed by a CA. Instead, you can create a self-signed certificate. However, as previously mentioned, please note that a self-signed certificate will always display SSL error messages in your web browser, and does not ensure the identity of the server.

   1. Log on to the op5 Monitor server as root via SSH.
       
   2. Execute the command below to create the self-signed certificate.
      

      openssl x509 -req -days 365 -in ~/localhost.csr -signkey /etc/pki/tls/private/localhost.key -out ~/localhost.crt

      This certificate will be signed for a year (365 days), but this can be changed by modifying the value of the -days argument in the command line above.

   Using your new certificate

   Look for instructions from your certificate vendor

   Regardless of whether your certificate comes from an internal or external vendor, there are usually instructions on how to set up the certificate for Apache. Directions for Apache in general also applies for Monitor, and instructions from your vendor may be easier to follow than this general instruction.
   1. You may have received multiple files from your vendor. In addition to a certificate (.crt), you may need a private key file as well as an "intermediate certificate".
   2. Upload the file(s) to the Monitor server. To avoid reconfiguration, name your files like the existing ones mentioned in the current httpd configuration (localhost.crt, localhost.key) put them in /root for now.
      (Skip this step in case of using a self-signed certificate.)
   3. Log on to the Monitor server as root via SSH.
   4. Create a backup of the current certificate (as localhost.crt.old) by executing the command below.
      

      cp -pv /etc/pki/tls/certs/localhost.crt{,.old}

   5. Copy the new certificate from the root directory:
      

      cp -pv ~/localhost.crt /etc/pki/tls/certs/localhost.crt

   6. You likely also need to replace your current private key file. Back it up:

      cp -pv /etc/pki/tls/private/localhost.key{,.old}

   7. Copy the new private key from the root directory:
      

      cp -pv ~/localhost.key /etc/pki/tls/private/localhost.key

   8. If you received an "intermediate certificate", place this in /etc/pki/tls/certs/, keeping the existing name (e.g. DigiCertCA.crt) and uncomment the line in /etc/httpd/conf.d/ssl.conf referring to SSLCertificateChainFile, and give it the correct path. Example:

      SSLCertificateChainFile /etc/pki/tls/certs/DigiCertCA.crt

      SSLCertificateChainFile may be deprecated in future EL8 releases of Monitor when Apache exceeds version 2.4.8
   9. Save the configuration file and restart Apache to use it:

      systemctl restart httpd

   10. Access your op5 Monitor server GUI using your web browser, and verify that no SSL error messages are seen. You should look both in the browser, from the client's point of view, and in the /var/log/httpd/ssl_error_log from the server's point of view.