Docusign Service Integration Authentication

2
votes

I am creating a service integration that will need to use my Docusign account. I began by looking into authentication info and found the Legacy Header page. This advises against using it for service integrations

Legacy Header authentication was formerly recommended for service integrations. DocuSign recommends new service integrations be built with Service Integration Authentication.

So I decided to go to that Service Integration Authentication page which states

Before an application can impersonate a user, the application must get consent directly from the user or from their account administrator.

Then in the granting consent section it states

User consent can start with either the Authorization Code Grant or the Implicit Grant.

However, both the Authorization Code Grant and the Implicit Grant pages state at the very top of the page

This grant is not suitable for service integrations.

So should I not use these grants? If I don't it leaves me back at using Legacy Header authentication. I have no problem with this but why advise against using it then advise against using the alternative as well? Am I missing something?

1
docusignapi

1 Answers

4
votes

I'm sorry that the documentation for Service Integrations is not clear. We will work to improve it.

TL;DR -- watch my screencast where I focus on this exact issue.

Here's the scoop:

The JWT flow is recommended for Service Integrations if you're writing the app for your own organization's use. If you're an ISV (if you'll be selling your software to DocuSign customers) then there are additional issues to be considered at this time.

To use the JWT flow and impersonate someone or a designated "system user" (the usual cases) then your app needs permission to do so. If you have Organization Admin enabled, your org admin can proactively grant permission for your app to impersonate anyone in your org.

You can also have each person individually grant permission. Eg, you create a user called "HR Dept" in DocuSign. You then login as the "HR Dept" and grant permission to the app to impersonate the "HR Dept."

A user grants permission to an app the first time they use it. But user's don't "use" Service Integrations! (As you discovered via the documentation.)

Here's the trick: Set up the app in DocuSign as both a Auth Code Grant app (set a redirect URI) and as a JWT flow app (create a public/private key pair). For convenience, set the redirect URI to an existing site. Eg, https://www.docusign.com

Then, once per user who will be impersonated, tell them to enter a specific URL into their browser. That URL is the first leg of the OAuth Auth Code Grant flow. It is

${AUTHENTICATION_URL}/oauth/auth?response_type=code&scope=${encoded_scopes}&client_id=${CLIENT_ID}&redirect_uri=${REGISTERED_REDIRECT_URI}`

# AUTHENTICATION_URL = https://account-d.docusign.com  (demo)
# AUTHENTICATION_URL = https://account.docusign.com  (production)
# CLIENT_ID = your integration key
# encoded_scopes = signature%20impersonation
# REGISTERED_REDIRECT_URI = https://www.docusign.com (or whatever
#                            you registered)

When the user enters the above url, DocuSign will ask them to log in and then ask them to grant the permissions (scopes) to your app.

Then you can run your JWT flow (no user required) and you're golden.

Added: Granting Consent is one time per user per integration key

Granting consent is a one time operation per user per integration key. So once your user(s) have granted consent, your application can keep re-running the JWT grant flow.

Caveats:

  • Only use the JWT grant flow when your app needs a new access token for the user being impersonated. Don't use the JWT grant flow before each API call! Only use the flow when the existing access token has expired or is about to expire.

  • If the user revokes consent to your app then your app will need to acquire consent again.