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