Debugging Insights Certificate Issues

News Knowledge Base
, , , ,
1

Challenges encountered with a certificate update for the Insights application.


Sometimes challenges with the Insights application are encountered after an Insights/Looker certificate change. Review the following steps to further investigate and resolve the issue.

How Certificates Work:

Many times, there are challenges in managing HTTPS certificates utilized for TLS encryption between client and server. The issue often arises due to a lack of clarity regarding the certificate's purpose and its associated requirements. Here's a very brief primer on the key details to know:

  1. The purpose of certificates is to make the internet safer (among other things).
  2. Anytime a browser connects to a website using HTTPS, a certificate is involved. A secure site looks like:
image.png
image.png335×142 8.55 KB

  1. A certificate is a document that can be used to establish if a website is trustworthy (using a long random alphanumeric string). How that trust is established is done using complex mathematical operations. But for our purposes, we need to know the following:
    1. Root Certificates are certificates that we trust directly. For these certificates, there exists an actual file on our computer that contains the certificate. Because the file exists on our computer in the right location, we trust it.
    2. Certificates can be chained together. So if Certificate A is present, which is trusted and it says to trust certificate B, then trust Certificate B. The correct term for this would be that Certificate A issued Certificate B. This can be extended further.
    3. When we connect to a site, it presents a certificate to the browser, if that matches one of the Root Certificates or if its issued by one of our Root Certificates, it can be trusted. If the site is trusted, then it is marked as secure by the browser.​​
    4. Behind the scenes, every certificate has a private key. This is used to issue certificates and it should never be shared. ( Share a certificate without sharing the private key)
  2. Certificates also have metadata. In the context of HTTPS the most important attribute is called the 'Subject Alternative Name' (SAN). This is the name of the server that is being connected to (usually the FQDN). Some admins might simple refer to this as the DNS name. For any URL, determine what the value of the SAN should be. Here are a few examples:
    1. https://google.com -> The SAN should be google.com
    2. https://uipath.com/docs -> The SAN should be uipath.com
    3. https://insights.mycompany.com/home -> The SAN should be insights.mycompany.com. The domain would be mycompany.com.
    4. https://insightslinux.mycompany.com/login -> The SAN should be insightslinux.mycompany.com. The domain would be mycompany.com.
  3. If the SAN does not match the URL being used, a browser will mark the site insecure (even if it trusts the certificate).
  4. A certificate can have multiple SAN entries. The SAN entry is always a valid DNS name.
  5. A few other things:
    1. There are what is called Public Root Certificates. These come from well well-known organizations (DigiCert, AWS, CloudFlare, etc). They not only issue certificates but they ensure that they only issue certificates to websites that own the domain. For example, no one but the company UiPath can request a certificate with the SAN attribute uipath.com from a public Root Certificate company because we own the domain.
    2. Internally within a company's intranet, a company can have its own Root Certificates. These are Private Root Certificates but are like public root certificates in the context of the company's intranet. Companies usually have an internal root certificate provider that is used for internal sites. This allows them to issue certificates for internal sites without having to buy certificates from a public certificate authority. For example, they might issue a certificate for a site called: rpa.mycompany.internal.
    3. For companies with internal root certificates, usually automatically install these certificates onto the machines connected to their intranet.
  6. This means that for a site to be secure the following conditions must be met:
    1. The SAN attribute matches the server name in the URL.
    2. The certificate presented by the website needs to be a Root Certificate or issued by a Root Certificate.
    3. This also means that UiPath cannot provide these certificates for end users. For us to issue a certificate for an on prem environment, either, we would have to own the domain or we would need to be given access to the company's internal Root Certificate's private key, which is something that should never be shared.
Create self-signed certs. These are new Root Certificates. However, these certificates would have to be installed on every user's machine manually and tend to lead to more complications. For example, if the certificate is not installed on a user's machine, they can usually bypass the certificate warning, but many other things would break.
  1. With the above in mind, these are the important things to know:
    1. Almost all companies have an internal root CA (I have never encountered a company that does not).
    2. Almost all companies have a well defined well-defined process for requesting a certificate issued by an internal root certificate. The biggest challenges are:
      1. Being aware of this process
      2. Understanding the SAN attribute and requesting the server name correctly.
    3. The same process used to issue a certificate for a Windows machine can be used for a certificate that will be used on a Linux machine.


Troubleshooting/Diagnosing:

  1. Note that Insights has two web servers. The web server is hosted on the Windows machine and the web server is hosted on the Linux machine. The Windows machine is the frontend service and the Linux machine is the backend service. However, a browser connected to Insights will connect to both services.
    1. See: Insights Architecture
    2. This means that both services need to have a valid certificate for HTTPS communication (It is possible to use one certificate, but that certificate has to have valid SAN names for both the Windows and Linux servers)
    3. Additionally, for both services the following applies: Using a Certificate for the HTTPS Protocol
  2. This article will address the Windows portion first
    1. For Windows, a few things to note:
      1. The URL hostname is defined at install time when the MSI asks for the Insights server URL. See: MSI Installer
      2. The settings provided at this stage are used to configure the IIS binding for the Insights site. IIS bindings are described here: IIS Binding Documentation.
    2. To see if there is a problem with the certificate, simply go to the Insights URL. If there is a problem with the certificate, the browser will display an error. In most cases, the browser will display a helpful error message.
      1. See Certificate Error Article (This article is used to diagnose robot errors, but the debugging steps are the same. Just use the Insights URL instead of the Orchestrator URL).
      2. Capture screenshots (and make sure to include the URL)
    3. If the issue is that the certificate is expired, or that the certificate needs to be updated follow: Updating the Portal Certificate in IIS.

If the issue persists:

  • If issues are encountered during the update, capture screenshots. Follow the below steps.
    1. If the issue is still not resolved for the Windows component, please raise a ticket. Include the following:
      1. Screenshots that were captured in the previous steps
      2. If the certificate shows insecure, try exporting the certificate. This can be done by clicking the 'Not secure' icon in the browser and viewing the certificate. In the certificate viewer, there should be an option to export. This is just the public key and not the private key, so this is safe
      3. Screenshot of the IIS binding settings from step 4 in the certificate change article
      4. Any other information on the steps that were taken?
    2. For the Linux portion:
      1. To see if there is a problem with the certificate, simply go to the Insights Looker URL.
        1. See Certificate Error Article (This article is used to diagnose robot errors, but the debugging steps are the same. Just use the Insights URL instead of the Orchestrator URL).
        2. Capture screenshots (and make sure to include the URL)

      2. For updates verify if the steps elaborated in the "Certificate Change Steps" section below to update the Insights Certificate at the Looker side are followed.

  • If these steps did not work, take a screenshot of the pre-installation tool and any errors encountered.
  • If there were any steps that were performed outside of the above, elaborate on the same.
  • Share the following with UiPath Support for further investigation:
      1. Share the following logs with us for further analysis: How To Collect All Looker Logs For Insights?
      2. Screenshots that were captured in the previous steps
      3. If the certificate shows insecure, try exporting the certificate. This can be done by clicking the 'Not secure' icon in the browser and viewing the certificate. In the certificate viewer, there should be an option to export. This is just the public key and not the private key, so this is safe
      4. Any other information on the steps that were taken?


Certificate Change Steps:

Follow these steps in order:

  • Export the Insights certificate with a private key as a PFX.
  • Copy the PFX to the Insights Linux machine
scp {certificateFolder}\NewInsightsCert.pfx InsightsUser@LinuxMachine:/Home/InsightsUser/NewInsightsCert.pfx
  • Download the script needed to update the certificate.
wget https://github.com/UiPath/Insights-Customer/blob/master/Scripts/OnPrem/certificateChange.sh
  • Update the file permissions to make it executable
chmod 755 certificateChange.sh
  • Run the script using the following command:
 ./certificateChange.sh -c {cert.pfx filename} -s {RHEL FQDN as listed in certificate SAN}.

You will be asked to provide the path to the PFX file and password (if needed for the certificate).