Securing your Connect webhook listener

Your Docusign Line of Business (LOB) application is ready for production. Your colleagues will send out Docusign signature requests from within the app. Plus, your app shows the status of the signature requests and automatically notifies the back office when a contract is signed.

The status and back office notifications are handled by your app’s Docusign Connect webhook listener. A listener is a web application with its own URL. The only thing special about a listener is that it never expects to be invoked by a person sitting at a web browser. Instead, it only expects to be called by the Docusign platform’s Connect system.

How can we assure ourselves that only Docusign will call our listener (access control) and that the client is guaranteed to be Docusign (authentication)?

We’ll handle the two problems of access control and authentication by using the security principle of “Defense in Depth.” It’s also called the “Castle Approach,” after the multiple layers of defensive lines and techniques that any good castle is equipped with. (Moats, walls, towers, narrow circular stairs, drawbridges, etc.)

Please note that this post does not offer any guarantees. It only provides an overview of multiple and complex security issues. Your InfoSec group or consultants need to review your servers, networks, firewalls, and related systems.

Connect webhooks: everything’s reversed

Normally, applications are the clients. They initiate requests to the Docusign platform, the server. But for Connect webhook listeners, everything’s reversed. Your listener will be the server for the status update notifications sent as requests initiated by Docusign. For the notification messages sent to your listener, Docusign is the client.

The moat: Check therequest characteristics

Since we know the characteristics of the good requests from Docusign, you should  configure your system to block any requests unless they are:

• HTTPS requests to the standard port 443. 

• POST requests. The Connect service only uses POST requests.

The drawbridge: SSL/TLS

SSL/TLS connections encrypt all communications between the client and the server. They protect against Man in the Middle attacks.

Docusign requires that SSL/TLS be used for Connect listeners in production. I suggest that you also use SSL/TLS during development with demo.docusign.net. In the future TLS will be required for the demo.docusign.net platform too.

Your server’s SSL certificate must be issued by a recognized root certificate authority (CA) to work with Docusign. Specifically, your SSL certificate's root CA must be in the Microsoft Trusted Root Certificate program used by Docusign. A list of the program's CAs and supported root certificates can be downloaded. The list is updated periodically.

Docusign validates your listener’s cert. It does not check your listener’s identity. What this means in practice is that your listener’s SSL certificate cannot be self-signed. It must chain upward to a certificate in the Microsoft list. You can use a free SSL certificate from the Let’s Encrypt CA.

The eall: Authentication and access control

There are two options for this part of your defenses. A Connect configuration can use either with Docusign, but not both:

• Use Mutual TLS to authenticate the client (Docusign) and access control to ensure that only Docusign can reach your listener. I covered Mutual TLS in this blog post.  This defense is implemented at the webserver or load balancer that negotiates the SSL/TLS connection with Docusign.

• Configure Docusign to digitally sign the Connect notification messages. Then your app can verify the signature to assure itself that the message was sent by Docusign and was not modified since it was sent. We’ll discuss this option in a future blog post.

The portcullis: Use a pre-shared secret

This defense acts both as access control and authentication. The listener URL you provide to Docusign can include one or more query parameters. Docusign will include them during its POST request to your listener.

For access control, your listener will first check that the request includes the expected query parameter and reject all requests that don’t. For authentication, your listener will additionally check the value of the query parameter. Remember that you can encode any values for the name and value of the query parameter. For this example, we’re using “pw” as the name of the query parameter.

To use a pre-shared secret, just set the URL accordingly in the Connect configuration. For example, https://listener\_url.example.com/listener?pw=secret

Remember that the complete URL, including its query parameters, is encrypted before it is sent across the internet. The URL and its query parameters are visible in various logs and configuration screens, including the Connect webhook configuration page.

Not recommended: IP whitelisting

In the 21st century, using Internet Protocol (IP) addresses as a form of authentication is not recommended by security experts. Instead, use Mutual TLS to authenticate Docusign, your server's client. Depending on the situation, IP addresses for SAAS services such as Docusign may need to be changed. Using IP addresses for authentication creates a "brittle" system that will need to be updated if there's a change.

Installation and debugging tips

Just as your defense is layered, it’s a good idea to layer your installation too. Add your defensive layers one by one, checking that they work as expected before adding another layer.

Monitoring

Just as all well-run castles have guards and watchers, you will need the same for your installation. Your system shouldn’t be considered secure unless you have a layered set of monitoring tools plus appropriate automatic and manual responses for different event types.

Load Testing

Depending on your Connect settings, each envelope may generate many different notification messages to your listener. And depending on your envelope volume, that could result in thousands or tens of thousands of notification messages being sent to your server by the Docusign platform. Docusign handles millions of messages a day; how many messages can your listener support?

The answer is to conduct some basic load tests of your listener. A blog post by 3Scale includes a useful overview of open source and SAAS load testers that can be used to test your listener.

Summary

Thanks for reading this far! Remember to have your plans and systems checked by your information security department or consultants.

Please let us know your experiences. Write us via developers@docusign.com. I'll be speaking at our MOMENTUM '17 conference in San Francisco from May 3-4. Developers can attend for free. Learn more and register for MOMENTUM '17 here.