Configure the Server SSL Certificates

Polarity Server Certificates

Polarity Clients require the Polarity Server to use a valid SSL certificate.  This certificate must be trusted by the workstation running Polarity Client or Polarity Web.  There are several options to meet this requirement including:

1. Buy a commercial SSL certificate

2. Generate a server certificate from an internal Certificate Authority (CA) 

3. Use a self-signed certificate and add it to the trusted store on all Polarity Client workstations

Not sure?

Options 1 and 2 are the preferred methods for all Polarity deployments in enterprise environments.

If you elect to generate a self-signed SSL certificate, please refer to the Self-Signed SSL Certificate Generation section

Certificate Format Requirements

Before installing your certificates, please ensure they are in the correct format.  

The SSL certificate and private key should be encoded in the PEM format using the PKCS8 container.  The public and private keys should be two separate files (typically a public .crt and a private .key file).  

The .crt file may also be generated as a .pem file.

• Private keys must not include a passphrase

• Private and public keys should not include content outside of -----BEGIN-----  and -----END----- blocks

• Filenames should be limited to upper- or lower case letters, digits (0-9), underscores, and dashes (no spaces or special characters)

Private Key Requirements

The private key must not have a passphrase on it. 

If your private key has a passphrase, you can generate a copy of the key without a passphrase by running the following command on the Polarity Server:

openssl rsa -in [original.key] -out [new.key]

Replace [original.key] with the name of your current key file and [new.key] with a new name, omitting the brackets ([]) in the command.

The original.key should be the key with the passphrase and new.key will be same key with the passphrase removed.  When running the above command you will be prompted for the passphrase.

You can check to see if you private key is in the right format by viewing the content of the key.  

cat new.key

The file content should look similar to this:

-----BEGIN PRIVATE KEY-----
MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQC1NALrZ6xcgCLO
// Additional Base64 encoded text
-----END PRIVATE KEY-----

Public Key Requirements

The public key certificate file for your server must match the private key.  This can be checked with the commands in the Troubleshooting section, below.  This key must be signed by some certificate authority (CA), even if that CA is the server itself (ie. a “self-signed” certificate).

If there is more than one CA in the CA chain (ie. one or more intermediate CAs in addition to the root CA), the public key certificate file installed in the web container’s /app/caddy/config directory must include all the certificates in the chain, starting with the most specific.  Multiple files will need to be combined into a single file.

To combine multiple certificate files, use this command:

cat cert1.crt cert2.crt cert3.crt > /app/caddy/config/server.crt

The above command will add the contents of three certificates (cert1.crt, cert2.crt, and cert3.crt) into the file /app/caddy/config/server.crt.  In this example, cert1 is the server’s certificate.  If there are additional certificates, simply add the file names to the cat command before the carat.

Check the format of the public key by viewing the content of the file with the "cat" command (cat /app/caddy/config/server.crt).  The output should look similar to this:

-----BEGIN CERTIFICATE-----
MIIEADCCAuigAwIBAgIBADANBgkqhkiG9w0BAQUFADBjMQswCQYDVQQGEwJVUzEh
// Additional base64 encoded text for most specific public key (the server's public key)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIID7TCCAtWgAwIBAgIJAJlLcgDO1uJuMA0GCSqGSIb3DQEBCwUAMIGMMQswCQYD
// Additional base64 encoded text for next most specific public key (an intermediate CA)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIFCDCCAvCgAwIBAgIIcL7NAf8zejcwDQYJKoZIhvcNAQELBQAwIzEUMBIGA1UE
// Additional base64 encoded text for least specific public key (the root CA)
-----END CERTIFICATE-----

CA Certificate Chains

If there is a CA certificate chain that your organization uses, such as GoDaddy or Zscaler, the full CA cert chain will need to be added to Polarity in order for the Integration Store to work correctly.

You can see the referenced chain with the following command to check the certificate issuer:

openssl x509 -in /app/certs/polarity.pem -issuer -noout

Obtain the full CA certificate chain (you can do this through your browser).  Add all CA certificates to the /app/certs/ca directory.

Note

CA certs can have any filename (no spaces or special characters) but need to be in PEM format and end with a .pem or .crt extension.

Once you've added your CA certificates to /app/certs/ca, restart the Server's Docker containers:

cd /app && ./down.sh && ./up.sh

If you do not have CA chain certificates …

They can typically be found by navigating to the Polarity Server via the browser and clicking on the “lock” or “shield” icon to the left of the URL.  This will pull up a dialog box that will allow you to navigate to the certificates the site is using and download them.

GoDaddy Certificate Example

The following is an example of downloading the GoDaddy CA certificate and installing it on the server.

mkdir /app/certs/ca
cd /app/certs/ca
wget https://certs.godaddy.com/repository/gd_bundle-g2.crt
cd /app && ./down.sh && ./up.sh

SSL Certificate Installation

The SSL certificate and key should be copied to your Polarity Server in the following locations.  The SSL certificates should be in PEM format in a PKCS8 container and match the below provided filenames.

cd /app && ./down.sh && ./up.sh

cd /app && ./down.sh && ./up.sh

-----BEGIN RSA PRIVATE KEY-----

openssl pkcs8 -topk8 -inform pem -in <private_pkcs1.pem> -outform pem -nocrypt -out server.key

-----BEGIN RSA PUBLIC KEY-----

openssl rsa -RSAPublicKey_in -in <public_pkcs1.pem> -pubout -out server.crt

openssl pkcs12 -in filename.pfx -out cert.pem -nodes

openssl pkcs12 -in filename.pfx -nocerts -out key.pem

openssl pkcs12 -in filename.pfx -clcerts -nokeys -out cert.pem

openssl rsa -in key.pem -out server.key

openssl pkcs8 -topk8 -inform PEM -outform PEM -in 
/etc/pki/tls/private/server.key.orig -out 
/etc/pki/tls/private/server.key -nocrypt

openssl x509 -in <cert.cer> -inform DER -text

openssl rsa -inform DER -outform PEM -in <mykey.cer>-out server.crt

openssl rsa -modulus -noout -in /app/certs/polarity_key.pem | openssl md5

openssl x509 -modulus -noout -in /app/certs/polarity.pem | openssl md5

openssl rsa -check -noout -in /app/certs/polarity_key.pem

docker exec -it polarity_platform bash
docker exec -it polarity_web bash

docker exec -it polarity_platform bash
openssl s_client -connect polarity_web:8443 -showcerts

docker exec -it polarity_web bash
openssl s_client -connect polarity_platform:4001 -showcerts

docker exec -it polarity_web bash
openssl s_client -connect integration-store.polarity.io:443 -showcerts

docker exec -it polarity_web sh
curl -v https://integration-store.polarity.io/api/repos