September 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

In July 2021, DocuSign will announce OAuth 2.0 support for SOAP applications and enable developers to use the new authentication feature.

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

By September 2022, over a year from now, 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 September 2022.

Go-Live updates

To enforce the new requirements, the automatic go-live process will be updated on August 16th 2021 to require applications to use OAuth v2.0 for authentication. This requirement will affect SOAP and 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. For the SOAP API, the access token can also be sent using an element within the SOAP header. Details will be provided with the OAuth for SOAP announcement in July.

The legacy X-DocuSign-Authentication header will not be supported in any form, including XML, JSON, SOBO, and OAuth v1 token formats.

For the SOAP API, neither the existing WS-Security UsernameToken SOAP header nor the X-DocuSign-Authentication HTTP header will be supported.

Send On Behalf Of

The eSignature SOAP and REST APIs 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 September 2022.

Must SOAP applications use OAuth 2.0 too?

Yes, all applications that use REST or SOAP must use OAuth v2.0 per the schedule listed above. OAuth 2.0 support for SOAP applications will be announced in July 2021.

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:

Larry Kluger
Author
Larry Kluger
Lead Developer Advocate
Published
Related Topics