Blog
Home/

Docusign adds support for PKCE

Author Rebecca Startzman
Rebecca StartzmanSoftware Engineer
Summary3 min read

We're adding support for Proof Key for Code Exchange (PKCE), an enhanced security feature for authentication.

    • What’s new?
    • Implementation is easy
    • When?
    • Additional resources

    Table of contents

    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 before PKCE

    Authorization Code Grant flow with 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. 

    Additional resources

    Author Rebecca Startzman
    Rebecca StartzmanSoftware Engineer

    Rebecca joined Docusign as a software engineer in 2020.  An expert in OAuth and OpenID, she works for our Login Platform group where she helps support Auth across the Docusign platform. You can find Rebecca at LinkedIn.

    More posts from this author

    Related posts

    • What Are API Services? Benefits & Uses
      Developers

      What Are API Services? Benefits & Uses

      Docusign Contributor
    • Fast-Track Your Extension Apps with Reference Implementations

      Fast-Track Your Extension Apps with Reference Implementations

      Author Karissa Jacobsen
      Karissa Jacobsen
    • Trending Topics: Latest from our forums (October 2024)
      Author Paige Rossi
      Paige Rossi
    Fast-Track Your Extension Apps with Reference Implementations

    Fast-Track Your Extension Apps with Reference Implementations

    Author Karissa Jacobsen
    Karissa Jacobsen
    Trending Topics: Latest from our forums (October 2024)
    Author Paige Rossi
    Paige Rossi

    Discover what's new with Docusign IAM or start with eSignature for free

    Explore Docusign IAMTry eSignature for Free
    Person smiling while presenting