October 2022: OAuth 2.0 required for all DocuSign API applications
As part of DocuSign’s continued commitment to security and reliability, we periodically review our products and APIs to ensure that they meet current standards for information security. DocuSign’s legacy authentication and older OAuth APIs do not meet current information security standards and will no longer be supported per the schedule listed below.
OAuth 2.0 uses modern authentication techniques, and passwords are never visible to the relying party (application). In addition, the OAuth 2.0 flows for user-present authentication (Authorization Code Grant and Implicit Grant) automatically support Single Sign-On (SSO). SSO is of great benefit to users and SSO support should always be provided by using OAuth.
For Independent Software Vendors (ISVs), an additional advantage of OAuth 2.0 is that it lowers the ISV’s exposure to information security issues because, when OAuth 2.0 is used, the user’s credentials are never handled by the ISV’s software.
Schedule
Since August 16, 2021, all new API applications must use an OAuth 2.0 flow for authentication. DocuSign legacy authentication and OAuth 1.0 will not be accepted for new applications.
In February 2022, DocuSign announced its new SOAP authentication strategy.
By October 4, 2022, all DocuSign customer, ISV, and partner API applications must use OAuth 2.0. Applications already in production must be upgraded to use OAuth 2.0 by then.
The schedule and related announcements will be published in the Product Release Notes through October 2022.
Go-Live updates
To enforce the new requirements, the automatic go-live process was updated on August 16th 2021 to require applications to use OAuth v2.0 for authentication. This requirement affects REST applications.
What types of authentication will no longer be available?
Only OAuth 2.0 Authorization Code, JWT, and Implicit grant flows will be supported. The resulting Bearer access token is sent using the Authorization request header field. See RFC6750 §2.1.
The legacy X-DocuSign-Authentication header will not be supported in any form, including XML, JSON, SOBO, and OAuth v1 token formats.
Send On Behalf Of
The eSignature REST API supported the Send on behalf of (SOBO) feature via the legacy authentication system. The OAuth equivalent of SOBO is to use the JWT Grant flow. JWT authentication is used to impersonate an accounted user, the equivalent of the SOBO feature. There is one difference: the JWT Grant flow requires the user’s GUID ID, their API Username. The Users:list API method can be used to look up a user’s GUID ID from their email address. Users’ email to GUID ID mappings are fixed and should be cached.
Any other change needed?
Yes: if your application needs the authenticated user’s name, email, account ID, base URI, or related information, then it must be updated to use the /oauth/userinfo API method instead of the obsolete login_information API call.
Are applications already in production required to update to OAuth 2.0?
Yes, they must be updated to use an OAuth 2.0 authentication flow by October 4, 2022.
Are there any exceptions?
We do not foresee any exceptions to the new policy. It is needed to assure the security of applications. DocuSign has supported OAuth 2.0 for over three years; our Developer Support and Professional Services groups are ready to help you. We also have an extensive set of OAuth 2.0 documentation and code examples that can be used.
I’m an ISV. I need new integration keys that don’t require OAuth 2.0 for my new customers.
If you’re a member of a DocuSign partner program, please send an email to partners@docusign.com and we will work with you on this issue. At the same time, please plan now to update your application to use OAuth 2.0 for DocuSign authentication per the schedule. OAuth 2.0 provides significantly better security and login options for our joint customers, and less InfoSec exposure for ISVs.
If you’re not yet a member of a DocuSign partner program, please join us (no charge) via this form. Then contact us about your application’s integration keys.
DocuSign recommends that ISVs should use a single integration key for all of their customers whenever possible. See this document.
Do you have resources to help my developers upgrade to OAuth?
Yes, see the following resources:
- Developer Center articles
- Introduction to OAuth video
- Integration Keys video
- Videos: How to migrate to OAuth 2.0 using a DocuSign SDK:
