Introducing OAuth for Connect: enhanced security for webhooks
At DocuSign, we understand that security is of the utmost importance to our customers. Starting with our Trust Center, which gives you access to the latest DocuSign security, compliance, legal, privacy, and system performance information, when and where you need it, we make ongoing investments toward protecting customer data and offer a number of features to help customers further secure their data. I’m pleased to share that, as part of this effort, we’re adding an enhanced security protocol called OAuth to DocuSign Connect.
What is Connect?
Connect is DocuSign’s webhook service that acts as a notification trigger that provides status updates to your application’s listener in real time. When an envelope changes state, such as from draft to sent, DocuSign Connect will send an event update to your listener with the new status of the agreement and any relevant information about document fields. This way, you can keep track of agreements without needing to constantly poll DocuSign for information. Because DocuSign Connect sends updates proactively, it can provide near-instantaneous notifications about agreements, giving you the most up-to-date information possible.
Comparing the two options for updating the status of your DocuSign envelopes and other events shows the advantages of DocuSign Connect:
- Polling: repeatedly requesting an update
- Webhooks: being notified when an update is available
To recap, polling constantly asks for an update whereas a webhook notifies you when the event has occurred.
As you can see from the technical diagrams above, the use of webhooks is a more efficient method of capturing updates to trigger workflows without overloading system resources. However, this does pose a challenge in regards to security. In order to secure the webhook with your application server, it needs to authenticate a connection with your user credentials. The security risk this poses is the amount of access an application now has to your company infrastructure, simply with your username and password. With many ports of entry into a company’s database, the need for robust, configurable security options is now more than ever a top priority.
Introducing OAuth for Connect
OAuth has become a popular way to share resources with applications, as it offers a more secure alternative to sharing your username and password. OAuth is an open authorization protocol that enables scoped access to resources, rather than granting total access to your account. This means that you can grant an application access to only the resources that it needs, rather than giving it complete access to your account. While OAuth offers several methods of range-based authentication, DocuSign Connect specifically uses the Client Credentials authentication grant type, which is a server-to-server communication protocol.
OAuth requirements
To enable OAuth, you will need Connect access in your DocuSign account.
- In the admin portal, find the Integrations side menu under Settings.
- Select Connect
- Select OAuth 2.0 tab
- Configure Settings
Configuring OAuth
To configure the desired application to receive DocuSign Connect event notification messages, it will require the following:
- The ability to direct an HTTP webhook to your application
- A defined set of credentials:
- Client ID: a username
- Client Secret: a password
- Customer parameters (optional): attributes such as scope or audience specific to your network
- HTTP URL for your webhook: The link where DocuSign will send notification triggers
- URL to an authorization server or OAuth service: the link to authenticate with application
- When you connect your DocuSign account, DocuSign will provide the defined set of credentials to the authorization server, which will respond by providing an access token.
- The access token is used to pass information back to the webhook. Rest assured, the access token is used primarily between the authorization server and DocuSign as a trusted parameter to pass information back and forth. The access token can also be verified with the authorization server to validate its authenticity.
Once you’ve configured OAuth for Connect, you’ll need to build your app to follow the authentication model in its communications with the DocuSign servers. The diagram below illustrates the process flow.
Summary
OAuth for Connect is available for account-level and envelope-specific webhooks. The addition of the OAuth security protocol to implement in your Connect-driven applications provides an added layer of protection keeping your data secure. DocuSign strives to offer and maintain the highest levels of security and is a trusted provider for millions of customers.
Please refer to our developer documentation to learn more about the new security model and what the structure looks like for each event. Please refer to our admin guide to learn more about setting up the configurations in the web application.
Ready to start building? If you’re already a DocuSign user, check out the OAuth for Connect in your Developer Demo account now or sign up for a free developer account. Not yet using DocuSign? Get started today. If you have any questions, comments, or suggestions for topics for other integrations, feel free to message developers@docusign.com.
