Use an Existing HTTPS Certificate Within Your Experience Cloud (Community) Domain

Introduction

Salesforce Experience Cloud (formerly Community Cloud) supports running each community in your org under a custom domain (e.g. community.mycompany.com instead of mycompany.force.com). To ensure security, communications between your users’ browsers and the communities in your org take place over HTTPS (e.g. HTTP over TLS). When running your community under a custom domain, you must upload an HTTPS certificate that matches your community’s custom domain. HTTPS certificates ensure your community domain’s authenticity to the public, and it’s critical to get the details of your certificate right prior to uploading it.

It’s possible to request a new HTTPS certificate or to reuse certain existing certificates in your community domain. Broadly, there are two options:

Not sure which option you need to use? Talk with your Information Technology (IT) team to determine whether you have an existing certificate or if you need a new one.

How do we Import an existing certificate and private key into Salesforce with a Java keystore (JKS) file?

To use an existing HTTPS certificate for your Salesforce Experience Cloud (formerly Community Cloud) custom domain, you must convert the certificate into a Java Keystore (JKS) or Bouncy Castle FIPS Keystore (BCFKS) file format and import it via Salesforce Certificate and Key Management (Setup then Security Controls then Certificate and Key Management then Import from Keystore). The conversion process varies based on the format of the certificate you currently have: PKCS#12 (.p12 or .pfx) contains the certificate chain and private key in one file; individual PEM or DER files store certificate and private key separately; and existing JKS or BCFKS files can be imported directly.

To import an existing certificate chain and private key into Salesforce, multiple options exist, based on the formats of the certificates and private key to import. Salesforce supports the Java keystore file format, but not all systems directly export that file format. Fortunately, it is possible to use the keytool command in the Java development kit to convert common certificate file formats into a Java keystore file.

A common format for storing a certificate chain -- the server or client certificate along with the intermediate certificates in its signing chain -- and its server or client certificate's private key is the PKCS#12 format, which contains those items within one file. Another possible format is a collection of individual certificate files and a separate private key file. Sections exist below for those two conversion scenarios. After converting the file into a Java keystore file, it is possible to import it into Salesforce.
 

• PKCS#12 (.p12, .pfx) File
• Individual PEM or DER Files
• Java Keystore File
   

PKCS#12 (.p12, .pfx) File

Before proceeding, be sure to install the Java development kit from Oracle if you do not already have Java installed. Download and install the appropriate version for your system. Be sure that the path to keytool or keytool.exe is within your PATH environment variable or, alternatively, fully qualify the path to the keytool or keytool.exe command when running the commands below.

To convert a PKCS#12 file into a Java keystore file, the source alias used for the certificate in the PKCS#12 file will need to be obtained. To obtain that information, run the following command on your PKCS#12 file, replacing pkcs12file.pfx with the filename of your PKCS#12 file. You will be prompted for the PKCS#12 file's private key encryption passphrase, which was set when the PKCS#12 file was created.
 
Run the following command to list the certificate alias in your PKCS#12 file. You will need this alias in the next step. Replace pkcs12file.pfx with your actual filename and enter the file passphrase when prompted.

keytool -list -keystore pkcs12file.pfx -storetype pkcs12   

The output will resemble the following. Take note of the alias, which is highlighted in bold below. The alias value in this example is le-384927abc3839f-829278-ee12. The value used in your file may be different, and it may more simply be the number 1.
 

Keystore type: PKCS12
Keystore provider: SunJSSE

Your keystore contains 1 entry                                                       
                                                                                                      
le-384927abc3839f-829278-ee12, Jan 29, 2016, PrivateKeyEntry,
Certificate fingerprint (SHA1): 99:68:C4:80:45:AF:9F:01:40:C5:BD:FB:0B:AB:CC:F0:99:9B:91:9D  

With the alias, it is possible to convert the PKCS#12 file into a Java keystore file with the following command. Replace pkcs12file.p12 with the filename of your PKCS#12 file. Replace keystorefile.jks with the filename that you want to use for the Java keystore file. Replace cert_dev_name_in_salesforce with the developer name that you want to use for the certificate within Salesforce. The developer name is the name that can be used by Apex code or the metadata API to reference this certificate. The developer name must begin with a letter and consist of only of alphanumeric characters or nonconsecutive underscores. This command will prompt you for a passphrase to use for encrypting the private key in the Java keystore file, and it will ask you for the passphrase of the PKCS#12 file being converted.

Note the alias value from the output above. Use it in the following command to convert the PKCS#12 file into a Java Keystore (JKS) file. Replace the placeholders with your actual filenames and your desired Salesforce certificate developer name. The developer name must begin with a letter and contain only alphanumeric characters or nonconsecutive underscores.

keytool -importkeystore -srckeystore pkcs12file.p12 -destkeystore
keystorefile.jks -srcstoretype pkcs12 -deststoretype jks -destalias
cert_dev_name_in_salesforce -srcalias le-384927abc3839f-829278-ee12 

After the keytool command completes, the resulting .jks file is ready to import into Salesforce. Go to Setup then Security Controls then Certificate and Key Management then Import from Keystore, select the file, and enter the passphrase when prompted.

After the command has run successfully, the keystorefile.jks file can be imported into Salesforce using the Import from Keystore button in the Certificate and Key Management setup page. Upon importing the Java keystore file, the imported certificate with the destination alias name should appear in the certificate list.

To Import the JKS file into Salesforce, please go to Setup | Security Controls | Certificate and Key Management | Import from Keystore
 
 

Individual PEM or DER Files

The PEM and DER file formats generally store certificates and private keys into separate files. The text-based PEM format allows the certificate chain and the private key to optionally exist within one concatenated file. A multitude of possible input configurations exists as a result when working with PEM and DER files. Generally, it is easiest to work with PEM files, and it is possible to convert DER files into PEM files for further processing.

Before proceeding, be sure to install the Java development kit from Oracle if you do not already have Java installed. Download and install the appropriate version for your system. Be sure that the path to keytool or keytool.exe is within your PATH environment variable or, alternatively, fully qualify the path to the keytool or keytool.exe command when running the commands below.

If you don't have OpenSSL installed, you will need to install OpenSSL for these steps. OpenSSL is built into Mac OS X and Linux, but is not built into Windows. Cygwin may be an option to install OpenSSL on Windows, and other options exist, too.

If one or more of the input files use the DER format, you will need to convert those into the PEM format. It is generally possible to determine if an input certificate or private key file is in the DER format by attempting to open that file in a text editor. If it is comprised of regular text characters and contains the phrases "BEGIN CERTIFICATE" or "PRIVATE KEY", then it is already in the text-based PEM format. If it is a seemingly random jumble of odd characters, then it is likely to be in the DER format.

To convert a DER certificate file into a PEM file, run the following openssl command. Replace der-certificate.crt with the filename of your DER certificate file and pem-certificate.crt with the filename that you want to use as the output file.
 
If any input files are in DER format (binary, unreadable in a text editor), convert them to PEM format first using the following commands.

openssl x509 -in der-certificate.crt -out pem-certificate.crt -inform der -outform pem

To convert a DER private key file into a PEM file, run the following openssl command. Replace der-privatekey.key with the filename of your DER private key file and pem-privatekey.key with the filename that you want to use as the output file.
 

openssl rsa -in der-privatekey.key -out pem-privatekey.key -inform der -outform pem

If you have more than one intermediate certificate, concatenate those intermediate certificate PEM files together into one text-based PEM file using a text editor. In the instruction below, this file is known as intermediate-chain.crt.

With the certificate chain and the private key available as PEM files, it is possible to use OpenSSL to convert these into a PKCS#12 file. To convert these into a PKCS#12 file, run the following command. Replace pem-certificate.crt with the filename of the PEM-formatted server or client certificate. Replace pem-privatekey.key with the PEM-formatted private key of that server or client certificate. Replace intermediate-chain.crt with the PEM-formatted file that contains all the intermediate certificates in the client or server certificate's signing chain.
 

openssl pkcs12 -in pem-certificate.crt -inkey pem-privatekey.key 
-certfile intermediate-chain.crt -export -out pkcs12file.p12   

The output pkcs12file.p12 file can now get converted into a Java keystore file using the following command. Replace pkcs12file.p12 with the filename of your PKCS#12 file. Replace keystorefile.jks with the filename that you want to use for the Java keystore file. Replace cert_dev_name_in_salesforce with the developer name that you want to use for the certificate within Salesforce. The developer name is the name that can be used by Apex code or the metadata API to reference this certificate. The developer name must begin with a letter and consist of only of alphanumeric characters or  nonconsecutive underscores. This command will prompt you for a passphrase to use for encrypting the private key in the Java keystore file, and it will ask you for the passphrase of the PKCS#12 file being converted.
 

keytool -importkeystore -srckeystore pkcs12file.p12 -destkeystore 
keystorefile.jks -srcstoretype pkcs12 -deststoretype jks 
-destalias cert_dev_name_in_salesforce -srcalias 1

The resulting JKS file can now be imported into Salesforce using the Import from Keystore steps described in the PKCS#12 section above.

After the command has run successfully, the keystorefile.jks file can be imported into Salesforce using the Import from Keystore button in the Certificate and Key Management setup page. Upon importing the Java keystore file, the imported certificate with the destination alias name should appear in the certificate list.

Additional Reference

Using Keystore Files

Java keystore files (JKS) or Bouncy castle fips keystore files (BCFKS), depending on your instance, may be imported as-is. Only the PrivateKeyEntry entries in the keystore are imported. Each entry of that type contains a certificate chain and a private key. Other entry types, such as trustedCertEntry, are ignored.The name of a PrivateKeyEntry becomes the developer name of the imported certificate, which can be used by Apex code or the metadata API to reference this certificate. The developer name must begin with a letter and consist of only of alphanumeric characters or nonconsecutive underscores.

To Import the JKS or BCFKS file into Salesforce, please go to Setup | Security Controls | Certificate and Key Management | Import from Keystore

Converting from JKS to BCFKS

At times it may be necessary to move certs from an instance that supports JKS to an instance that supports BCFKS. To do this you must download bc-fips-1.0.2.jar from https://www.bouncycastle.org/fips-java/ and run the following command, replacing [keystore name] with the name of the keystore, to convert from jks to bcfks:
 

keytool -importkeystore -srckeystore [keystore name].jks 
-destkeystore [keystore name].bcfks -srcstoretype jks -deststoretype bcfks 
-providerclass org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider 
-providerpath bc-fips-1.0.2.jar

Converting from BCFKS to JKS should not be necessary as all instances should accept BCFKS keystore type, but if needed you can convert from BCFKS to JKS with the following command:
 

keytool -importkeystore -srckeystore [keystore name].bcfks 
-destkeystore [keystore name].jks -srcstoretype bcfks -deststoretype jks 
-providerclass org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider 
-providerpath bc-fips-1.0.2.jar