Authorization Code Grant authentication

Authorization Code Grant is a type of OAuth 2.0 flow used to obtain an access token. Docusign supports two versions of this flow:

• Confidential Authorization Code Grant, which should be used by apps that can secure a secret key.
• Public Authorization Code Grant, which does not require that your app secure a secret key.

Confidential Authorization Code Grant

Confidential Authorization Code Grant is an OAuth 2.0 flow used by server-hosted integrations to obtain an access token.

In the Confidential Authorization Code Grant flow, your client integration obtains consent from an individual to perform actions on their behalf, then receives an authorization code that can be exchanged for an access token, which is required to make API calls. You can use Confidential Authorization Code Grant to authenticate if:

• Your users have Docusign accounts and log in to your integrated application individually.
• Your integration is hosted on a server, with clients accessing via browser interface or client-side app.

If you use a single login for all users in your integration, you should use JWT Grant. If your integration does not use a client/server architecture (such as most single-page and mobile integrations) and therefore does not have a secure location to store a secret, use Public Authorization Code Grant.

Confidential Authorization Code Grant has the following advantages and disadvantages, relative to the other supported grant types:

Advantages of using Confidential Authorization Code Grant

• This grant is suitable for all general use cases.
• Only one authentication flow is used, regardless of what operation is performed or who is performing it. This makes Confidential Authorization Code Grant implementations simpler and more straightforward than JWT implementations.
• This grant is very secure because the secret key is stored on your secure web server.
• Provides an access token with a lifetime of 8 hours, by default. This supports integrations whose users log in on a near-daily basis. For situations where users log in daily, you can request a special extended scope that enables almost indefinite refresh of tokens.
• Provides a refresh token that makes it easy to renew your access token when it is close to expiration. For details, see Using refresh tokens.
• You can optionally include a Proof Key for Code Exchange (PKCE) challenge to add an additional layer of security.

Disadvantages of using Confidential Authorization Code Grant

• The user must be present to authenticate and have actions performed on their behalf. This means that the Confidential Authorization Code Grant grant flow can’t be used by autonomous applications.
• Unlike Public Authorization Code Grant, you must be able to secure a client secret.

Public Authorization Code Grant

Public Authorization Code Grant (ACG) is an OAuth 2.0 flow used to obtain an access token. It is recommended for apps that cannot secure a secret key, such as single-page apps and native apps.

Public Authorization Code Grant works just like Confidential Authorization Code Grant, but it does not require that you secure a secret key. Instead, it uses Proof Key for Code Exchange (PKCE) to add an additional security step that ensures that the app that finishes the flow is the same as the one that started it.

In Public ACG, you supply two additional parameters when you make the authorization code request: code_challenge and code_challenge_method.

• code_challenge is a cryptographically random string that you supply, hash with S256, and encode via Base64URL. The unhashed string is called the code_verifier.
• code_challenge_method is the algorithm that will be used to hash the code challenge. The only supported value is S256.

Later, when you exchange your authorization code for an access token, you also include the original cryptographically random string (the code_verifier). The server hashes this code_verifier string with S256, encodes it via Base64URL, and checks to ensure that the result matches your supplied code_challenge. If the value of both strings match, then the server has verified that the requests came from the same client and will issue an access token.

When to use Public Authorization Code Grant

You should use Public Authorization Code Grant (with PKCE) to authenticate if your users have Docusign accounts and log in to your integrated application individually. If you use a single login for all users in your integration, you should use JSON Web Token (JWT) Grant instead.

Because Public Authorization Code Grant does not require that you securely store a secret key and provides additional security over Implicit Grant, it should be used instead of the Implicit Grant for all use cases.

Advantages of Public Authorization Code Grant

• This grant is suitable for all general use cases.
• It provides the same level of security as Confidential Authorization Code Grant.
• Your app does not need to keep a client secret secure, enabling you to use this grant without needing a web server.
• It is simpler and more straightforward than JWT.
• It provides an access token with a lifetime of eight hours by default. This supports integrations whose users log in on a near-daily basis. For situations where users log in daily, you can request a special extended scope that enables almost indefinite refresh of tokens.
• It provides a refresh token that makes it easy to renew your access token when it is close to expiration.

Disadvantages of Public Authorization Code Grant

• The user must be present to authenticate and have actions performed on their behalf. This means that the Public Authorization Code Grant grant flow can’t be used by autonomous applications.

Next steps

• For a step-by-step walkthrough of how to get an access token using this grant, see How to get an access token with Confidential Authorization Code Grant or How to get an access token using Public Authorization Code Grant.
• For an in-depth walkthrough of the Authorization Code Grant, how it works, and how to use it, see our OAuth Authorization Code Grant webinar.