From the Trenches: Updates to mTLS with OAuth for Docusign Connect
Docusign now supports using Mutual TLS with OAuth for Docusign Connect, giving you a more robust way to authenticate notifications from our webhook service.
When you have a webhook listener on the internet, it is very important to secure access to your listener and any resources to which it grants access. This makes sure that information is only flowing in from authenticated sources and thus prevents unwanted and potentially malicious data from entering your system. Docusign offers five different mechanisms to authenticate Docusign Connect Event messages; that is, to make sure that the Event messages are coming only from Docusign and not from someone else.
OAuth authentication
HMAC message signing and authentication
HTTP Basic authentication
Mutual TLS authentication
Digital signature (SOAP only, deprecated)
OAuth for Docusign Connect allows administrators to grant scope-based access to resources to Docusign Connect while ensuring integrity and authenticity. Docusign Connect specifically uses the Client Credentials authentication grant type, which is a server-to-server communication protocol. For an example of how to set up an Authorization Server on Azure, how to obtain an access token, and then how the Access Token is being supplied in the Connect Event message, see Andy Singh’s blog post. In this post, I’m going to cover using Mutual TLS (mTLS) with OAuth to authenticate Docusign Connect notifications.
What is Mutual TLS (mTLS)?
Mutual TLS is a mechanism that enables a server to authenticate the identity of the client that is connecting to it. Larry Kluger’s Mutual TLS blog post has more information on the TLS protocol, plus a few examples of how you can set it up and debug it. Mutual TLS enables your server to confirm that the Connect event being received is in fact provided by Docusign and has not been sent by a third party.
Using mTLS with OAuth
OAuth and mTLS are both mechanisms that offer security for your infrastructure. The benefit of enabling both is that both operate on different layers of the network infrastructure so they are able to complement each other. mTLS ensures that the connection is from Docusign, and adding OAuth adds authentication at the application level . This extra security makes a connection less vulnerable to forged message attacks.
Previously, if you had mTLS enabled on your Connect configuration, your listener could request and validate Docusign’s x.509 certificate even when an access token is supplied. However, the authorization server wasn’t able to request the certificate before granting a token.
What is new?
With the addition of mTLS with OAuth, your authorization server will now be able to request Docusign Connect’s x.509 certificate to verify its identity before the OAuth grant flow starts. Refer to the figure below for what the changes look like.
As an additional security option, access token integrity (“Mutual-TLS Client Certificate-Bound Access Tokens'') is now available. To support this, your Authorization Server can associate the access token it issues with Docusign Connect’s x.509 certificate. Then, the Connect message’s access token can be both checked for validity and further checked that the message’s origin (Docusign Connect) is the same client (same certificate) that requested the access token.
Implementing mTLS, OAuth for Connect, and mTLS Client Certificate-Bound Access Tokens are the responsibility of the customer, since all of these features are implemented, configured, and controlled by the customer’s server hardware and software.
Docusign recommends that customers decide which level of Connect message authenticity checks are appropriate for their business case and networking environment. Often a combination of Basic Authentication (implemented by the web server) and HMAC checks (implemented by the application software) are the right answer.
Docusign Professional Services can assist customers in configuring mTLS and mTLS Client Certificate-Bound Access Tokens.
We recommend testing this out in your demo account to ensure everything works as expected.
Additional resources
Karan Kaushik began his Docusign career in January 2022. As a front-line developer support engineer, Karan enjoys working on complex technical problems. He is passionate about using technology to make people's day-to-day lives easier and simpler, leveraging his array of experience across information technology, cloud operations, and software development.
Related posts
Discover what's new with Docusign IAM or start with eSignature for free
