Print this page

Mutual Authentication to Salesforce

Knowledge Article Number 000240864

Salesforce supports mutually authenticated transport layer security (TLS) on inbound connections. This allows secure server-to-server connections initiated by a client using client certificate authentication, and means that both the client and the server authenticate and verify that they are who they say they are. Previously, only the ability to secure outbound calls was supported, by using mutually authenticated TLS connections.


This feature includes:

  • Client certificates uploaded and stored in the database, where they are used for verification.

  • A mechanism to prevent falling back to the standard TLS port.

  • The ability to add certificates signed by a certificate authority (CA) trusted by Salesforce.


Setting up mutual authentication requires action by both the organization administrator and the API client manager. This feature is intended for API use and not for user interface (web browser) use. This feature was announced in the Winter '14 Release Notes.

Administrator Actions

  1. Contact Salesforce Support to have mutual authentication turned on for your organization.

  2. Generate the Certificate Signing Request (CSR) for the client certificate the API client will present when attempting to establish the mutually authenticated TLS connection to Salesforce. It’s important that the client certificate be signed by one of the Salesforce trusted root certificate authorities. The list is maintained here: Outbound Messaging SSL CA Certificates.

  3. Once the certificate is signed, upload the certificate to the organization at Security Controls | Certificate and Key Management. Upload the signed client certificate to the Mutual Authentication Certificates table in order for Salesforce to properly validate the client certificates presented by the client when initiating an inbound mutually authenticated TLS connection.

  4. Enable the Enforce SSL/TLS Mutual Authentication user permission for the API client user. This permission forces the use of port 8443 for secure connections.

  5. This permission can be added to a profile or assigned to an individual user with a permission set.


API Client Manager Actions

Configure the API client to connect on port 8443 and present the client certificate. This configuration process is very environment-specific and not under the control of Salesforce. The client needs to be configured to present the complete certificate chain (client and all intermediate certificates) to Salesforce for the certificate to be properly validated.


Additional information exists in Configure Your API Client to Use Mutual Authentication.

Client Certificate Operation

Client certificates are trusted using two layers that separately perform certificate chain validation and identity verification.

Certificate Chain Validation

When your API client connects to your organization's API endpoint on port 8443, that endpoint sends a client certificate request during the TLS handshake. That request has an empty list of client certificate authority names. The API client needs to send a client certificate chain -- the client certificate along with all intermediate certificates that exist in the trust path between the client certificate and its root certificate -- to Salesforce during the TLS handshake.


Salesforce uses standard certificate chain validation to ensure that the client certificate chain is signed properly and is trusted by a root certificate in Salesforce's Outbound Messaging SSL CA Certificates list. This includes a temporal check of all certificates' validity timestamps along with revocation checks using certificate revocation lists. The signature of each certificate in the chain is validated using the public key in its issuer's certificate.

Certificate Identity Verification

The client certificate's identity information is passed along in the request to the Salesforce application servers. Within Salesforce's application servers, a verification of the client certificate's identity occurs if the user has the "Enforce SSL/TLS Mutual Authentication" user permission enabled.


When a user with the "Enforce SSL/TLS Mutual Authentication" user permission enabled accesses Salesforce, the client certificate's identity information is used to look up the mutual authentication certificate from the org. If the certificate is found and matches the client certificate that was sent to Salesforce, access is granted, but if it does not match or is not found, then access is denied. If no client certificate is presented by the API client, then that user's access to Salesforce is denied.


Users that do not have the "Enforce SSL/TLS Mutual Authentication" user permission enabled are able to access Salesforce either without a certificate or with any certificate that chains up to a root certificate in the list at Outbound Messaging SSL CA Certificates.

promote demote