From DocuSign, Consent_required, Administrative consent. I'm Larry Kluger,
lead developer advocate for DocuSign. DocuSign supports three different OAuth flows for APIs,
authorization code grant, JWT grant, and implicit grant. See the show notes
for links to a video and documentation about the OAuth authentication flows.
To meet modern information security standards, an authorized person must provide consent
before an application can act on behalf of or impersonate a user. Application consent
is tracked by DocuSign. It is not stored in a cookie or elsewhere on the browser.
The authorization code and implicit grant flows smoothly handle the consent step when the user
authenticates with the application for the first time. This is called in-band consent
since it occurs within the authentication flow. In-band consent is not available for the JWT grant
since the JWT grant is used by autonomous applications, where user is often not present.
For JWT grant, an out-of-band consent step is needed. Because in-band consent is more
convenient, DocuSign recommends that Independent Software Vendors, ISVs, use authorization code
grant whenever feasible. DocuSign time provides three options for JWT out-of-band consent,
administrative consent, individual consent, and ISV administrative consent.
This video discusses administrative consent for the JWT grant. A future video will
discuss individual consent. ISV administrative consent is required if an ISV application whose
integration key is managed by the ISV wants to use administrative consent for users on your account.
More information on this consent flow is listed in the show notes.
Individual consent can always be used since it can be used with any type of DocuSign account.
Many ISVs uses individual consent since all DocuSign
customers can use it. I'll discuss ISV issues more at the end of this video.
If you've received the consent_required error, well,
first thing is congratulations. Receiving this error when you're using the OAuth JWT
grant flow indicates that your application is creating a JWT request correctly.
That covers a lot of software territory. Next, you just need to obtain consent for the user
your application is impersonating and you'll be ready to make API calls.
Administrative consent is the best JWT consent experience
since your users don't need to do anything. But administrative consent has several requirements.
Your account needs the access management with SSO also feature. SSO itself is optional.
Your email DNS domain must be claimed.
Note that consent is only given to your users whose email addresses match a claimed domain.
And your application's integration key must be managed by an account within the organization.
There are five steps for using administrative consent, checking availability of the access
management feature; setting up your organization; claiming your email domain;
granting administrative consent; and testing. Step one is to check that your account has
the access management with SSO feature. This feature's included with some DocuSign plans
and is optional for others. You do not need to implement SSO. The feature can be requested for
developer accounts by contacting customer support. See the show notes for details.
Step two is to set up your DocuSign organization. You will first set up the organization itself,
then add your account or accounts to the organization. The organization administration
guide provides full details on this step. See the video show notes for links to the documentation.
Step three is to claim the email domain or domains that your DocuSign account members use.
A single email domain, such as mycompany.com, can be claimed both by your developer account
for testing and by your production account. If your users have email addresses that use
subdomains of your claimed domain, then you also need to claim each subdomain that's used.
See the documentation for details on how to claim your email domain.
Step four is to grant administrative consent by using your organization admin tool. Be
sure to spell the consent permissions correctly. They are not spell checked.
For the e-signature API you will need the signature and impersonation scopes.
Depending on your application and the APIs it uses, you may need additional scopes too.
Note that synchronization of the permissions within DocuSign can take up to five minutes.
So if your application doesn't work immediately, try it again a couple of minutes later.
Test your work by configuring your application with the user ID of a user in your account
who was not previously granted consent. Test that the JWT grant succeeds
due to your administrative consent for the user's email domain.
Here's a demonstration. First, we'll test a command line application that uses a JWT grant.
The JWT grant flow fails with the consent-required error message.
Now let's grant consent administratively. Click Settings to go to the e-Signature administration
application. Click the Switch to button to go to the organization's administration application.
Next, we open the Domains page to confirm that the email domain has been claimed.
We can see that the worldwidecorp.us domain has been claimed. Next, we go to the Connected Apps
page. Click the Authorized Application button to start the administration consent process.
Choose the application's name and enter the scopes in the permissions field.
For this e-signature application we need the signature and impersonation scopes.
Click Add to complete the process.
Now back to the command line application. This time, the JWT grant succeeds due to administrative
consent. Check which OAuth scopes your application requires. If you provide administrative consent
for the wrong scopes, then your application will still receive the consent-required error.
Administrative consent only applies to account users whose email addresses use your claimed
email domain. For example, if you have a user whose email address is a gmail address, then you
won't be able to provide administrative consent for them. They'll need to use individual consent.
After using your organization's administration tool to provide administrative consent,
DocuSign may take a couple of minutes to fully process and propagate the consent
across its entire infrastructure. You can claim a domain for the DocuSign developer
environment and claim it again for the production environment.
But a domain cannot be claimed by two different production organizations.
DocuSign highly recommends that ISVs should manage the integration key
for their applications. Since the ISV controls the integration key,
it is not shown on the customer's administrative consent list of keys. Therefore,
ISVs must use an additional API to enable their customers to use administrative consent.
And since most DocuSign customers do not have access to the organization administration tool,
DocuSign currently recommends that ISVs should use the authorization code grant flow in preference to
the JWT grant if they can. If JWT grant is used, ISVs should plan on using individual consent.
That's it. Thank you for developing with DocuSign.
Remember to check the show notes for the documentation links.