DocuSign adds support for PKCE
As part of DocuSign’s commitment to empower our developer community, we continue to make investments in providing features and support to enable developers to build first-class client applications with the highest security standards. Today we are ready to announce support for Proof Key for Code Exchange (PKCE) for client applications using the Authorization Code Grant flow to authenticate with DocuSign. This feature will be launched in our March release. This also lays the groundwork for us to add support for the more secure Authorization Code Grant flow for public applications (applications that can’t store a secret), which are currently limited to the Implicit Grant flow, in a future release.
What’s new?
Many DocuSign developers have applications that use either OAuth 2.0’s Authorization Code Grant or Implicit Grant flows to securely communicate with DocuSign, Authorization Code Grant being the most widely used and recommended option. Since the inception of OAuth there have been several optional additions to the OAuth 2.0 specification, including PKCE. PKCE is an optional step that can be performed in the Auth Code Grant flow to provide an additional layer of security. We’re also providing a configuration option for your apps to require that they use PKCE to authenticate with Authorization Code Grant.
Implementation is easy
If your application can generate a random string and hash it via the SHA 256 algorithm, then you can make use of PKCE. This is accomplished by providing two new values in the calls your app makes to DocuSign. These values are called code_challenge and code_verifier and are created by your app. The code_challenge value is a SHA256 hash of the code_verifier value. When your app requests authorization from DocuSign, it sends code_challenge as a query parameter along with the other information you’re already sending, such as your client_id. Then, when you exchange the authorization code for the access token during the Authorization Code Grant flow, you provide the code_verifier that DocuSign will hash via SHA256 to verify that it matches the code_challenge provided in the first request. If they match, the Authorization Code Grant flow continues as usual and you receive the access token. This ensures that your client is the same in both the request and grant steps, and that if somehow the authorization code gets intercepted by some other party, they aren’t able to exchange it for the access token.
Authorization Code Grant flow before PKCE
Authorization Code Grant flow with PKCE
What does a code_verifier look like?
From the PKCE Specification:
code_verifier = high-entropy cryptographic random STRING using the
unreserved characters [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"
from Section 2.3 of [RFC3986], with a minimum length of 43 characters
and a maximum length of 128 characters.
ABNF for "code_verifier" is as follows.
code-verifier = 43*128unreserved
unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"
ALPHA = %x41-5A / %x61-7A
DIGIT = %x30-39
https://www.rfc-editor.org/rfc/rfc7636#section-4
When?
You will start to see PKCE be honored in requests in the developer environment (account-d.docusign.com) Monday, March 6, and it will be live in DocuSign production environments about a week later. Please note that if your client application is doing PKCE incorrectly, this could cause failures for you when we start honoring PKCE in OAuth requests. You will be able to manage the settings for PKCE enforcement for your app in the Apps and Keys page in the eSignature Admin console at the end of March.
