Mutual TLS | Docusign | Documentation

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 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). TLS is the successor to SSL and it’s an excellent standard with many features.

Software as a Service (SAAS) applications, including the Docusign Signature Service, normally act as API servers. They respond to requests from clients including web browsers and applications. However, webhook applications such as Docusign Connect 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 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. The blog post 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 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 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 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: