SSL Certificates

When Precision Bridge connects to external services (such as ServiceNow, JIRA, or databases), it verifies each server's identity using SSL certificates. In many enterprise environments, the certificates that Precision Bridge trusts by default are not sufficient, and connections will fail with SSL verification errors.

This guide explains why this happens, how to fix it, and how to obtain the right certificate -- either by exporting it from your browser or by requesting it from your IT team.

When Custom Certificates Are Needed

Precision Bridge runs inside a Docker container, which means it has its own isolated set of trusted certificates. Unlike applications installed directly on your computer, it does not automatically inherit the certificates trusted by your Windows, macOS, or Linux machine. This is the most common reason SSL errors occur -- even though your browser can reach a service without issues, Precision Bridge may not trust the same certificates.

You will typically need to add a custom certificate if your organisation:

Uses a corporate proxy with SSL inspection -- Many enterprise networks route web traffic through a proxy that inspects encrypted connections. These proxies re-sign traffic using your organisation's own certificate, which Precision Bridge does not recognise by default. This is the most common cause of SSL errors.
Connects to services using an internal Certificate Authority (CA) -- Some organisations run their own CA to sign certificates for internal services, rather than using a well-known public CA.
Uses a firewall that performs TLS decryption -- Similar to proxy-based inspection, some network appliances decrypt and re-encrypt traffic with their own certificate.

Common Error Messages

If you see any of the following when testing a connection, a custom CA certificate is most likely needed:

CERTIFICATE_VERIFY_FAILED
unable to get local issuer certificate
self-signed certificate in certificate chain

Tip: When you encounter one of these errors on the connection test screen, Precision Bridge will display a help message with a direct link to the SSL Certificates settings.

How to Add a Certificate

Open Precision Bridge in your browser
Navigate to Preferences from the main navigation menu
Select SSL Certificates under the Security section in the sidebar
Click Upload Certificate
Select one or more certificate files (.pem or .crt format)
The certificate will appear in the table showing its filename, subject, and upload date

After uploading, go back to your connection and click Test again. The new certificate will be used automatically -- there is no need to restart the application.

Removing a Certificate

To remove a certificate you no longer need:

Navigate to Preferences > SSL Certificates
Click the delete icon next to the certificate
Confirm the deletion

Note: Connections that rely on the removed certificate may fail after deletion.

Obtaining Your Organisation's CA Certificate

If you are unsure which certificate file to upload, there are two approaches: you can export it yourself from your browser, or you can request it from your IT team.

Exporting a Certificate from Your Browser

If the service you are connecting to (e.g. your ServiceNow instance) is accessible from your browser on the same computer, you can export the CA certificate directly. This is the quickest way to obtain the right certificate, because your browser already trusts it.

Google Chrome or Microsoft Edge:

Visit the URL of the service you are connecting to (e.g. https://your-instance.service-now.com)
Click the padlock icon (or tune icon) in the address bar
Click Connection is secure, then click Certificate is valid -- this opens the certificate viewer
Select the Details tab
In the certificate hierarchy at the top, select the topmost (root) certificate -- this is the CA certificate you need
Click Export and save the file with a .pem extension

Mozilla Firefox:

Visit the URL of the service
Click the padlock icon in the address bar
Click Connection secure > More information
Click View Certificate -- this opens a new tab with the certificate details
In the certificate chain shown at the top, click on the leftmost (root) certificate
Scroll down and under Miscellaneous, click the PEM (cert) download link to save the root CA certificate

Safari (macOS):

Visit the URL of the service
Click the padlock icon in the address bar
Click Show Certificate
Expand the certificate chain and select the topmost (root) certificate
Drag the certificate icon to your desktop to save it, or use the Export option if available

Important: Make sure you select the root certificate at the top of the chain, not the server's own certificate at the bottom. The root certificate is the one that identifies your organisation's CA or proxy.

Once you have exported the file, upload it in Preferences > SSL Certificates as described above.

What to Ask Your IT Team

Ask your IT department for your organisation's root CA certificate (sometimes called the "corporate root certificate" or "proxy CA certificate") in PEM format. This is the certificate your organisation uses to sign or re-sign SSL traffic on the corporate network. Most IT teams will be familiar with this request, especially if you mention that you are running an application inside a Docker container that does not have access to the host machine's certificate store.

If your IT team provides the certificate in a different format (such as .cer, .der, or .pfx), ask them to convert it to PEM format, or let them know that the file needs to contain text starting with -----BEGIN CERTIFICATE-----.

Identifying the Right Certificate

The certificate you need is the CA (Certificate Authority) root certificate, not the certificate of the server you are connecting to. In a typical corporate proxy setup:

Your proxy intercepts HTTPS traffic and re-signs it with your company's CA certificate
Your company's computers trust this CA because it has been installed on them by IT
Precision Bridge runs in Docker and does not have this CA, so it rejects the re-signed traffic

Uploading the CA root certificate to Precision Bridge solves this by adding it to the list of trusted authorities.

If You Cannot Obtain the Certificate

If your IT team is unavailable or the process is slow, you can temporarily work around the issue by disabling SSL verification on individual connections (see the Verify SSL section below). However, this is not recommended for long-term use.

Certificate File Requirements

When uploading certificates, the files must meet these requirements:

File extension: .pem or .crt
File format: PEM (a text file that starts with -----BEGIN CERTIFICATE-----)
Content: One or more CA certificates (you can include multiple certificates in a single file)
Binary/DER format certificates are not supported -- ask your IT team for the PEM format version if needed

Verify SSL Setting

Each API connection in Precision Bridge has a Verify SSL toggle in its Advanced settings tab.

Enabled (default, recommended): Precision Bridge verifies the server's certificate, including any custom certificates you have uploaded. This is the secure option.
Disabled: SSL verification is skipped entirely. The connection will work regardless of certificate issues, but this is insecure and not recommended for production use.

Best practice: Always keep SSL verification enabled and upload the appropriate CA certificate rather than disabling verification. Disabling verification should only be used as a temporary measure while waiting for the correct certificate.

Troubleshooting

I uploaded a certificate but the connection still fails

Check you have the right certificate. You need the CA root certificate (the certificate that signed the server's certificate), not the server's own certificate. The certificate subject shown in the Preferences table should match your organisation's CA name.
Re-test the connection. After uploading, click Test on your connection again. New certificates are picked up automatically for any new connection test.
Check with your IT team. There may be multiple certificates in the chain (root and intermediate). Ask your IT team if you need to upload additional intermediate CA certificates.

The connection works in my browser but not in Precision Bridge

This is expected in corporate environments. Your browser uses your computer's trusted certificate store, which your IT team has configured with the organisation's CA certificates. Precision Bridge runs in Docker with its own certificate store and does not have access to your computer's certificates. Uploading the CA certificate in Preferences > SSL Certificates resolves this.

Next Steps

Once you have added the required CA certificate, return to your connection and test it. If you continue to experience SSL issues, contact help@precisionbridge.net for assistance.