Salesforce certificates and key pairs are used for signatures that verify a request is coming from your organization. They are used for authenticated SSL communications with an external web site, or when using your organization as an Identity Provider. You only need to generate a Salesforce certificate and key pair if you’re working with an external website that wants verification that a request is coming from a Salesforce organization.
You can export all your certificates and private keys into a keystore for storage or import certificates and keys from a keystore. This allows you to move keys from one organization to another. The exported file is in the Java Keystore (JKS) format, and the imported file must also be in the JKS format.
There are two Scenarios in which the use of these Certificates is mandatory.
Salesforce acting as the client:
When sending outbound messages, delegated authentication requests or Apex callouts to secure/SSL endpoints(e.g. https://myintegration.acme.com), a Salesforce.com organization (acting as the client) will only trust the target host (that will act as the server) if this presents a certificate signed by a root Certification Authority (CA) included in the list shown in the below link. In other words, in this scenario self-signed certificates are not allowed to be used by the target host.
Salesforce trusts only root certificate authority (CA) certificates, with few historical exceptions. Salesforce’s certificate trust policy is to require server and client certificate chains to include all intermediate certificates that exist between the server or client certificate and the chain’s root certificate. Salesforce will not honor requests to add intermediate certificates to its trust list. Salesforce trusts many generally trusted root certificates, but not all. Review the list at Outbound Messaging SSL CA Certificates for the root CA certificates that Salesforce trusts
When using mutual authentication/2-way SSL, Salesforce.com can present a self-signed certificate to the target host (that must present a CA signed certificate to Salesforce), provided that this certificate has been configured in the target host (installed in the target server’s keystore).
Salesforce acting as the server:
When a Salesforce organization is Single Sign On enabled using SAML, the organization plays the role of the Service Provider (SP). In this case Salesforce acts as the server and the configured Identity Provider (IdP) acts as the client, and it’s allowed to present a self-signed certificate.
When sending outbound messages, delegated authentication requests, and SAML assertions (both in the SP and IdP initiated flows), Salesforce will present the CA-signed or Self-Signed certificate configured under Setup | Security Controls | Certificate and Key Management | API Client Certificate.
On the other hand, Apex callouts may specify which certificate (from the list found at Setup | Security Controls | Certificate and Key Management) will Salesforce present to the target host. You need to use a Common Name for the cert that you control – for instance something rooted in your own domain (e.g. mycompany.com). There is no need to try and get a certificate in the salesforce.com domain.
A chain of trust is designed to allow multiple users to create and use software on the system, which would be more difficult if all the keys were stored directly in hardware. It starts with hardware that will only boot from software that is digitally signed. The signing authority will only sign boot programs that enforce security, such as only running programs that are themselves signed, or only allowing signed code to have access to certain features of the machine. This process may continue for several layers.
What should be the correct order of intermediate certificates in the certificate chain of customer’s application (endpoint) server?
Your application (endpoint) server must send any intermediate certificates in the certificate chain, and the certificate chain must be in the correct order. The correct order is:
- Server certificate.
- Intermediate certificate that signed the server certificate if the server certificate was not signed directly by a root certificate.
- Intermediate certificate that signed the certificate in step 2.
- Any remaining intermediate certificates. Do not include the root certificate authority certificate. The root certificate is not sent by your server. Salesforce already has its own list of trusted certificates on file, and a certificate in the chain must be signed by one of those root certificate authority certificates.
During the SSL handshake, the server sends the client a certificate to authenticate itself. The client uses the certificate to authenticate the identity the certificate claims to represent.
An SSL-enabled client goes through these steps to authenticate a server’s identity:
- Is today’s date within the validity period? The client checks the server certificate’s validity period. If the current date and time are outside of that range, the authentication process does not go any further. If the current date and time are within the certificate’s validity period, the client goes on to step 2.
- Is the issuing Certificate Authority (CA) a trusted CA? Each SSL-enabled client maintains a list of trusted CA certificates. This list determines which server certificates the client will accept. If the distinguished name (DN) of the issuing CA matches the DN of a CA on the client’s list of trusted CAs, the answer to this question is yes, and the client goes on to step 3. If the issuing CA is not on the list, the server is not authenticated unless the client can verify a certificate chain ending in a CA that is on the list.
- Does the issuing CA’s public key validate the issuer’s digital signature? The client uses the public key from the CA’s certificate (which it found in its list of trusted CAs in step 2) to validate the CA’s digital signature on the server certificate that is being presented. If the information in the server certificate has changed since it was signed by the CA, or if the CA certificate’s public key doesn’t correspond to the private key that was used by the CA to sign the server certificate, the client does not authenticate the server’s identity. If the CA’s digital signature can be validated, the client treats the server’s certificate as a valid “letter of introduction” from that CA and proceeds. At this point, the client has determined that the server certificate is valid. It is the client’s responsibility to take step 4 before it takes step 5.
- Does the domain name in the server’s certificate match the domain name of the server itself? This step confirms that the server is located at the same network address that is specified by the domain name in the server certificate. Although step 4 is not technically part of the SSL protocol, it provides the only protection against a form of security attack known as a “Man-in-the-Middle Attack.” Clients must perform this step and must refuse to authenticate the server or establish a connection if the domain names do not match. If the server’s actual domain name matches the domain name in the server certificate, the client goes on to step 5.
- The server is authenticated. The client proceeds with the SSL handshake. If the client does not get to step 5 for any reason, the server that is identified by the certificate cannot be authenticated, and the user is warned of the problem and informed that an encrypted and authenticated connection cannot be established.
To use two-way SSL authentication, send a certificate with your callout that was either generated in Salesforce or signed by a certificate authority (CA). Sending a certificate enhances security because the target of the callout receives the certificate and can use it to authenticate the request against its keystore.
To enable two-way SSL authentication for a callout:
- Generate a certificate.
- Integrate the certificate with your code. See Using Certificates with SOAP Services and Using Certificates with HTTP Requests.
- If you’re connecting to a third party and using a self-signed certificate, share the Salesforce certificate with them so that they can add the certificate to their keystore. If you’re connecting to another application within your organization, configure your Web or application server to request a client certificate. This process depends on the type of Web or application server you use.
- Configure the remote site settings for the callout. Before any Apex callout can call an external site, that site must be registered in the Remote Site Settings page, or the callout fails.
If the callout specifies a named credential as the endpoint, you don’t need to configure remote site settings. To set up named credentials, see “Define a Named Credential” in the Salesforce Help.