Print this page

Custom Domains: Using an Existing HTTPS Certificate With Your Community

Knowledge Article Number 000232390
Description

Introduction

Salesforce 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:

My community needs a new certificate

If your community will need a new HTTPS certificate, you can follow the instructions in Help & Training to configure & download a new Certificate Signing Request to give to your certificate authority.

I have an existing certificate for my community domain

If your company already has a certificate that matches the domain your community will run under, you can take the steps detailed below to import that certificate into a Java keystore (JKS) file to prepare it for upload to your org.
 

It’s important to make sure that your certificate matches the domain your community will be running under. For example:

COMMUNITY DOMAIN: community.mycompany.com

WILDCARD CERT: *.mycompany.com

NON-WILDCARD CERT: community.mycompany.com


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 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

The PKCS#12 file format conveniently stores a certificate chain and a private key within one file and is commonly used for backing up certificates. The Certificate Management within Windows and Windows Server can export to this file format. The private key in a PKCS#12 file is encrypted with a passphrase.

a PKCS#12 file contains a peer certificate, all the CA certificates in the chain, and the private keyBefore proceeding, be sure to install the Java development kit from Oracle at http://www.oracle.com/technetwork/java/javase/downloads/index.html 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.
 

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.
 

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 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 at http://www.oracle.com/technetwork/java/javase/downloads/index.html 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 at https://www.cygwin.com/ 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.
 

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

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.


 

Java Keystore File

A Java keystore file 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 file into Salesforce, please go to (Setup | Security Controls | Certificate and Key Management | Import from Keystore)





promote demote