Installing Private Certificate Authority

If you're organization is using a private/custom Certificate Authority (CA) to sign internal SSL certificates, you may need to install the CA's public certificate file onto the the Polarity Server to trust certificates signed by your organization's CA.

This most commonly occurs when you have an integration connecting to an internal resource over TLS (i.e., https). It can also occur if your integrations are connecting to an external resource through an internal proxy or other network device that has an SSL certificate installed that is signed by your private CA.

In both cases, you must install the public certificate of your organization's CA onto the Polarity Server.

Installing a Certificate Authority

Copy the CA's public certificate file to /etc/pki/tls/certs

cp mycert.crt /etc/pki/tls/certs/mycert.crt

In this example the public cert is named mycert.crt but the filename can be anything. The file should contain one or more trusted certificates in pem format. Note that if you have multiple certificates you will need to copy all the certificates into a single crt or pem file.

The CA's public certificate file should be in pem format. If you output the cert to the console it will be in plain ascii text (not binary).

Next, change the certificate's owner to the Polarity Server daemon user (polarityd):

chown polarityd.polarityd /etc/pki/tls/certs/mycert.crt

Set the SELinux permissions on the file to match those assigned to the server.crt file in /etc/pki/tls/certs/:

chcon --reference=/etc/pki/tls/certs/server.crt /etc/pki/tls/certs/mycert.crt

Next we will need to let Polarity know about the new CA certificate by editing the server's .env file. By default the .env file is not writable. To make it writable by root you can run the command:

chmod u+w /app/polarity-server/.env

Open the file /app/polarity-server/.env for editing. For example:

vi /app/polarity-server/.env

Add the following to the bottom of the .env file (adjust the filename as necessary):

/app/polarity-server/.env

# When set, the well known "root" CAs (like VeriSign) will
# be extended with the extra certificates in the given file.
# The file should consist of one or more trusted certificates
# in PEM format.
NODE_EXTRA_CA_CERTS=/etc/pki/tls/certs/mycert.crt

After you're done editing, you can disable writing of the .env file with the command

chmod u-w /app/polarity-server/.env

Restart the Polarity Server process for the change to take effect.

systemctl restart polarityd

Troubleshooting

Cert cannot be read

If for some reason the certificate could not be loaded by server you will see an error that looks like this in the server logs:

2021-02-24T09:34:43.459Z - error: Integration Error collected from Standard Error
{
  stderrString: 'Warning: Ignoring extra certs from `/etc/pki/tls/certs/mycert.crt`, 
  load failed: error:02001002:system library:fopen:No such file or directory',
  id: ''
}

(in this example NODE_EXTRA_CA_CERTS was set to /etc/pki/tls/certs/mycert.crt and the mycert.crt file does not exist).

Try grepping the server logs to find this error if it exists:

cat /app/polarity-server/logs/polarity-server.log | grep "load failed"

Cert is not valid

If the above error does not exist then the most common issue is that the provided CA is invalid or does not contain the full certificate chain (e.g., it could be missing an intermediate certificate). To verify that the provided CA file is valid you can use the openssl command to try and connect to the host using your CA:

openssl s_client -showcerts -CAfile {{ca.pem}} -connect {{hostname}}:443

Replace {{ca.pem}} with the path to the CA file (in our example, /etc/pki/tls/certs/mycert.crt) and replace {{hostname}} with the hostname of the server you want Polarity to be able to connect to. A large amount of text will be output but if you see something like this:

Then that means the CA is not valid.

Another way to test is if you have the certificate of the server you are trying to connect to. If you have the web server’s certificate you can run the following command to verify the cert:

openssl verify -verbose -CAfile ca.pem server.crt

In this example ca.pem should be the CA and server.crt is the certificate on the web server we’re trying to connect to with an integration.

If you don’t have the server.crt file you can download it to the polarity server using the following command:

echo -n | openssl s_client -connect {{HOST}}:{{PORT}} | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > ./{{HOST}}.crt

This command will write out a file called {{HOST}}.crt (replace {{HOST}} with the name of the host) and {{port}} with the port number the host is listening on (typically 443). You can then verify the file using the openssl verify command:

openssl verify -verbose -CAfile /etc/pki/tls/certs/mycert.crt {{HOST}}.crt