> You are reading the Docusign Developer Documentation. For clean Markdown of any page, append .md to the page URL. > > Documentation indexes by section: > - APIs and SDKs: https://docusign.docs.buildwithfern.com/docs/llms.txt > - Platform 101: https://docusign.docs.buildwithfern.com/platform/llms.txt > - Extension Apps: https://docusign.docs.buildwithfern.com/extension-apps/llms.txt > - Docusign CLI: https://docusign.docs.buildwithfern.com/docusign-cli/llms.txt > > Authentication (OAuth, JWT Grant, M2M): https://docusign.docs.buildwithfern.com/platform/auth > Webhooks and Connect: https://docusign.docs.buildwithfern.com/platform/webhooks > > OpenAPI specifications: https://docusign.docs.buildwithfern.com/openapi.json > MCP server: https://docusign.docs.buildwithfern.com/_mcp/server # Mutual TLS > This guide describes how mutual TLS authentication and authorization works and how your integration should implement it. You can add *mutual TLS authentication and authorization* to your Docusign Connect configuration to guarantee the identity of the server to the client and the identity of the client to the server, and provide a two-way encrypted channel between the two. This guide describes how mutual TLS authentication and authorization works and how your integration should implement it. This is an advanced topic for Connect applications and assumes that you have basic knowledge of the Connect product, including: * How to create and edit Connect subscription configurations * The difference between receiving regular XML notification messages from Connect and using Connect in SOAP mode with a SOAP service * Three techniques for creating a Connect subscription configuration by using: * The Admin tool to create an account-level Connect subscription * The eSignature API * The **eventNotification** object with the [Envelopes:create](/docs/esign-rest-api/reference/envelopes/envelopes/create) API or SDK method to create an envelope-specific Connect subscription Any time you use a web browser to connect to a secure site using the **HTTPS** protocol, you’re using [Transport Layer Security (TLS)](https://www.ietf.org/rfc/rfc5246.txt). TLS is the successor to SSL and it’s an excellent standard with many features. [Software as a Service (SAAS) applications](https://en.wikipedia.org/wiki/Software_as_a_service), including the Docusign Signature Service, normally act as API servers. They respond to requests from clients including web browsers and applications. However, [webhook](https://en.wikipedia.org/wiki/Webhook) applications such as [Docusign Connect](https://support.docusign.com/s/document-item?bundleId=vob1727899215236\&topicId=ctv1583277395112.html) reverse the usual roles of SAAS clients and servers to eliminate the need to poll the SAAS system. When Docusign Connect is used with a customer or ISV application, Docusign Connect is the client. When it has a notification message ready for delivery, Connect will make a request to the customer’s server. The customer’s server is also known as the *listener* since it listens for incoming notification messages generated by the webhook. When connecting to a webhook application, such as Docusign Connect, confirming the identity of the server is not enough because the customer or ISV is providing the server. Therefore, it is important to confirm the identity of the client—in this case, Docusign. To guarantee that the request to your Connect listener (your server) is really from Docusign Connect, we recommend the following solutions: * **Mutual TLS:** Optional feature for TLS that enables the server to authenticate the identity of the client. Mutual TLS can be configured for Docusign Connect in either XML or JSON modes. This guide focuses on how to configure mutual TLS for several popular web servers. * **HMAC:** Docusign Connect enables you to secure your Connect listener with HMAC, an industry standard symmetric hashing system. Once HMAC is enabled, special header values will be included in your Connect messages that you can use to verify that the message was sent by Docusign Connect (authenticity) and that the message contents are exactly the same as they were at the time of sending (integrity). ## Mutual TLS and Access Control Mutual TLS provides authentication of the client's identity. However, that isn’t enough; your server must also implement access control (authorization) to ensure that only authorized clients can send requests to your server. You can also implement access control using the [Connect HMAC](/platform/webhooks/connect/hmac) option. This is recommended over mutual TLS because it guarantees both that the message was sent by Docusign and provides an end-to-end message integrity check. ## Background: The TLS Handshake Protocol When you connect to a web site with **HTTPS**, the TLS handshake protocol is used to negotiate and set up a secure, encrypted channel between the client and the server. The handshake protocol consists of a series of required and optional messages sent between the server and the client. The handshake protocol and its messages are described in the [TLS 1.2 standard](https://www.ietf.org/rfc/rfc5246.txt). The blog post [Traffic analysis of a TLS session](https://megamorf.gitlab.io/2020/03/03/traffic-analysis-of-a-tls-session/) by Álvaro Castro-Castilla is also helpful for understanding the TLS handshake protocol. ## TLS: Authenticating the Server The server sends its digital [X.509](https://en.wikipedia.org/wiki/X.509) certificate (and any intermediate certificates) to the client, which then validates them against its list of pre-trusted root certificates. Most clients use the Microsoft or Mozilla set of trusted root certificates to validate exactly who the server is. When you’re browsing the web, the result of this process is an icon in the browser's address bar (usually a lock icon) indicating that your browser has established a trust relationship with the server and is using an encrypted channel for communications with it. You can select this icon to see details of the secure connection. ## Mutual TLS: Authenticating the Client To start the optional Mutual TLS process, the TLS handshake **Certificate Request** message is sent by the server to the client. The customer’s web server must be configured to use Mutual TLS. The configuration steps are server-specific and are discussed for several popular servers later in this guide. The **Certificate Request** message includes a list of Distinguished Names of root certificates that the server trusts. It requests the client (Docusign in our case) to respond with its own certificate and any required intermediate certificates. The client responds with a **Client Certificate** message. It includes the client’s certificate and any required intermediate certificates that chain to one of the Distinguished Names listed in the **Certificate Request** message. After sending the **Certificate Request** message and receiving a reply, the server [validates](https://tools.ietf.org/html/rfc5280#section-6) the client’s certificate. When validation is successful, the server has authenticated the client. ## Configuring Docusign Connect to respond to a Mutual TLS request Mutual TLS is enabled for one or more custom Connect configurations in either the sandbox or production versions of Docusign Connect. Note that: * Mutual TLS can be used for XML or SOAP Connect configurations. * If Mutual TLS is configured, then SOAP messages cannot be digitally signed. * If you’re programmatically creating the Connect configuration, set the `signMessageWithX509Certificate` field to `true`. * If you’re using the **eventNotification** settings in the [Envelopes:create](/docs/esign-rest-api/reference/envelopes/envelopes/create) method, set the `signMessageWithX509Cert` field to `true`. * **Require Mutual TLS** in the Admin tool is not used at this time. To enable mutual TLS, you must check the **Enable Mutual TLS** option. ## Configuring mutual TLS on the server (your application) Your Connect webhook application’s listener either includes a web server or is a client of a web server, depending on your application’s development stack. Mutual TLS must be enabled and configured on the server that negotiates the TLS connection with the Docusign client. The following topics show how to configure popular web servers for mutual TLS: * [How to configure mutual TLS for the Apache 2 web server](/platform/webhooks/mutual-tls/mutual-tls-apache2) * [How to configure mutual TLS for the F5 load balancer](/platform/webhooks/mutual-tls/mutual-tls-f5) * [How to configure mutual TLS for NGINX](/platform/webhooks/mutual-tls/mutual-tls-nginx) * [Mutual TLS: Stuff you should know](https://www.docusign.com/blog/developers/dsdev-mutual-tls-stuff-know) > This guide describes how mutual TLS authentication and authorization works and how your integration should implement it. ## Docs - [Troubleshooting mutual TLS](https://developers.docusign.com/platform/webhooks/mutual-tls/tls-troubleshooting.md) - [How to configure mutual TLS for NGINX](https://developers.docusign.com/platform/webhooks/mutual-tls/mutual-tls-nginx.md): To enable the NGINX web server to request mutual TLS from Docusign Connect, follow the steps outlined in this guide. - [How to configure mutual TLS for the Apache 2 web server](https://developers.docusign.com/platform/webhooks/mutual-tls/mutual-tls-apache2.md): This topic demonstrates how to enable an Apache 2 server to request mutual TLS from Docusign Connect. - [How to configure mutual TLS for the F5 load balancer](https://developers.docusign.com/platform/webhooks/mutual-tls/mutual-tls-f5.md): This topic demonstrates how to enable F5 to request mutual TLS from Docusign Connect and provide access control based on the certificate's fingerprint/thumbprint.