Blog
Home/

From the Trenches: Updates to mTLS with OAuth for Docusign Connect

Karan Kaushik
Karan KaushikDeveloper Support Engineer
Summary4 min read

Docusign now supports using Mutual TLS with OAuth for Docusign Connect, giving you a more robust way to authenticate notifications from our webhook service.

    • What is Mutual TLS (mTLS)?
    • Using mTLS with OAuth
    • What is new?
    • Additional resources

    Table of contents

    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. 

    1. OAuth authentication

    2. HMAC message signing and authentication

    3. HTTP Basic authentication

    4. Mutual TLS authentication

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

    Message flow between DocuSign, your authentication server, and your listener server

    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
    Karan KaushikDeveloper Support Engineer

    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.

    More posts from this author

    Related posts

    • Developers

      Breaking the Language Barrier: Why Large Language Models Need Open Text Formats

      Dan Selman
      Dan Selman
    • Understanding Levenshtein Distance: Applications to AI-Generated Text

      Vincent Pan
      Vincent Pan
    • Paige Rossi
      Paige Rossi

    Breaking the Language Barrier: Why Large Language Models Need Open Text Formats

    Dan Selman
    Dan Selman

    Understanding Levenshtein Distance: Applications to AI-Generated Text

    Vincent Pan
    Vincent Pan
    Paige Rossi
    Paige Rossi

    Discover what's new with Docusign IAM or start with eSignature for free

    Explore Docusign IAMTry eSignature for Free
    Person smiling while presenting