Transport Layer Security (TLS)

The Transport Layer Security (TLS) protocol is a widely used method to encrypt communications over a network and is core to HTTPS. TLS is the successor of the deprecated Secure Socket Layer (SSL) standard.

One-way (standard) TLS is applied by default without additional configuration in a Salesforce org, and enables HTTPS browser communication as well as HTTPS encryption for inbound and outbound integrations with external systems.

Mutual TLS provides an additional level of trust verification (client authentication) for inbound integrations, and can be configured for Salesforce by following the steps outlined below.

It's important to note that TLS and Mutual TLS offer security at the network layer, and are independent of user authentication. Typically, an integration secured by TLS or Mutual TLS should also require additional user authentication, which takes place over HTTPS through an OAuth flow or equivalent.

This section was co-authored with Martin Vyskocil, who wrote the original draft following our discussions on mutual TLS in the context of the JWT bearer flow (during which Martin corrected a misunderstanding I had around how these processes fit together!) A big thanks too to Charlie Guo, who reviewed our diagrams and notes and contributed further improvements, and Gianluca Calcagni who gave great suggestions for additional details to add.

Standard (One-Way) TLS

Diagram with steps of one-way TLS
  • TLS (Transport Layer Security) takes place at the network layer and precedes all HTTPS traffic, including user authentication
  • The client may be a browser or a client application participating in server-server integration
  • One-way TLS protects against impersonation of the server, as the server proves its identity to the client by demonstrating possession of its private key
  • The goal is for the client and server to establish a secure connection by establishing cryptographic keys that will be used to protect data in transfer
  • The shared session key required for HTTPS is generated from the pre-master key, client and server random numbers - both client and server require all of these to generate matching keys
  • Server identity is conferred by its ability to decrypt the pre-master secret to generate a session key matching the one generated by the client

When Salesforce acts as the Client (e.g. Apex callout)

  • Salesforce will only trust a CA signed certificate from the server

When Salesforce acts as the Server (e.g. Apex REST service)

  • Salesforce will present its CA-signed certificate (this certificate is managed by Salesforce and independent of the customer's org)
  • A client can connect to the My Domain login URL via port 443
Documentation
https://datatracker.ietf.org/doc/html/rfc5246
https://levelup.gitconnected.com/deep-dive-into-tls-handshake-e029e28e2eb3

Mutual TLS

Diagram with steps of mutual TLS
  • Mutual TLS (MTLS) prevents security from being compromised by requiring the client to prove its identity to the server in addition to the server proving its identity to the client
  • This mechanism provides a convenient way to ensure that the right server application can be accessed by the right set of client applications (SaaS applications share the same infrastructure, domain name, and IP ranges, so this protects against attacks leveraging alternative instances of public cloud applications)
  • As MTLS (applied at the network layer) is often used in combination with OAuth authentication and authorisation flows (which take place in the application layer), this provides an additional layer of security
  • Client identity is conferred by server verifying the signature of the CertificateVerify message (the transcript up to this point, signed with the client's private key)
  • As with one-way TLS, server identity is conferred through its ability to generate a matching session key

When Salesforce acts as the Client (e.g. Apex callout)

  • Salesforce will only trust a CA signed certificate from the server
  • Salesforce can present either a CA signed or self-signed certificate. For Apex and Named Credentials callouts any certificate in the org can be specified. For outbound messages, SAML assertions, AJAX proxy and delegated authentication the certificate used will be the one set as the API Client Certificate in Certificates and Key Management

When Salesforce acts as the Server (e.g. Apex REST service)

  • Salesforce will only accept a CA signed certificate from the client, and this certificate must be uploaded to the org's truststore - the repository of accepted MTLS certificates (see setup steps below)
  • Salesforce will present its CA-signed certificate (this certificate is managed by Salesforce and independent of the customer's org)
  • A client should connect to the My Domain login URL via port 8443
  • To set up MTLS with Salesforce acting as the server:
    • Raise a ticket with Salesforce
    • Assign the "Enforce TLS/SSL Mutual Authentication" and "API Only User" permissions to the Integration User
    • Upload the client's CA Signed certificate to the Mutual TLS section under Certificate and Key Management in Setup (the Salesforce org's truststore)
Documentation
https://blog.superpat.com/2018/01/25/salesforce-mutual-authentication-part-1-th…
https://dzone.com/articles/implementing-one-way-and-two-way-ssl-mutual-authen
SSL certificates that are supported by Salesforce
Certificates in mutual authentication
Steps to set up a mutual authentication certificate
Configure your API client to use mutual authentication