Broadly speaking, apps integrated with DocuSign come in two flavors:
User Applications run in the foreground. The app’s user logs in and initiates activities. To integrate with DocuSign, the application asks the user to login to DocuSign using the OAuth Authorization Code Grant or Implicit Grant flow. With OAuth, the application will never see the user’s password. And with SSO, the user only needs to enter her password once per day (depending on the organization’s security policies).
Service Integrations run quietly in the background doing their job. For example, they may automatically send out on-boarding agreements to new employees or partners once an internal database is updated. Or automatically process customer contracts signed with DocuSign, automatically updating corporate IT systems and provisioning the new customer in the company’s applications.
In general, a Service Integration:
- Runs in the background and
- Does not have a person available to login.
In the old days, Service Integrations would store a copy of a user’s email/password and use them to make API calls using the DocuSign legacy authentication header. DocuSign continues to support this authentication flow.
But we don’t want to store user account passwords with apps!
The OAuth solution for Service Integrations, the JWT (JSON Web Token) flow, is now available for DocuSign and I recommend that you use it for new integrations. Brian Wishan’s blog post provides excellent reference information on the DocuSign OAuth JWT flow.
In this post, I’ll discuss the new OAuth JWT recipe that I’ve written and some tips and tricks for using OAuth JWT.
The new OAuth JWT recipe includes the details you need for using the JWT flow. It also includes three working examples for Node.JS, PHP, and a bash script. They are designed to be run from the shell. (Remember, service integrations run in the background!)
Consent is needed!
The JWT flow usually involves a user account, like the legacy authentication flow. Depending on what API calls the app will make, the user account may or may not need elevated privileges. The user account may also be used by a person or it may be a user account that is dedicated for use by the integration.
When your app creates the JWT token, the user’s user_id is included as a parameter.
The first time your app sends its JWT for a user to DocuSign, your app will usually receive an error response:
This tells your app that the user needs to grant consent to the app.
Via the JWT flow, your app will be acting as the user. Or in the OAuth vernacular, it will be impersonating the user. So the app needs to be granted the signature and impersonation permissions (or scopes as we say in OAuth-land).
The easiest way for a user to grant consent is to execute a specific URL. That URL has the same format as the URL used to initiate the OAuth Authentication Code Grant flow.
Your app should provide the URL to your users. Its format:
- SERVER is https://account.docusign.com (production) or https://account-d.docusign.com (developer sandbox).
- CLIENT_ID is your app’s integration key.
- The redirect_uri (shown here as https://docusign.com) must be the exact same as was configured for the integration key in the DocuSign Administration tool.
The URL is requesting permission for the two scopes. %20 is the escape code for a space character; the two scopes are separated by the space character.
In response, DocuSign will authenticate the user, and then ask her to grant your app the two requested permissions:
After permission is granted, you’ll be able to use the OAuth JWT flow to impersonate that user.
My app don’t need no stinkin’ consent!
If your DocuSign account is set up with Organization administration and SSO, then your organization administrator can proactively grant the needed permissions to your app.
As we can see from this discussion so far, the OAuth JWT flow includes the Send On Behalf Of (SOBO) capability. Some details are different but, in general, OAuth JWT flow can be used to impersonate any user, once permission has been granted.
Creating the JWT
It is not so simple to create a JWT. I strongly recommend that you use a software library to create your JWT. Free open source JWT libraries are available for many different software languages and stacks. Just do a web search.
Is it better to use impersonation (SOBO) instead of making users login to my app and DocuSign?
I hear this question a lot. If your user has logged into your app, why should we make them log in again to DocuSign? Why not use OAuth JWT so your app can impersonate them?
My response is that it is always better to use the OAuth user application flows, Authentication Code Grant and Implicit Grant, if you can. Those flows enable your security policymakers to implement, for example, two factor authentication. If a user application OAuth flow is being used, then your application (via OAuth) will automatically incorporate the new security policy.
There are many new user authentication policies and techniques being developed in the industry. As they’re investigated and added by DocuSign and identity provider services, they’ll only be available if your application uses an OAuth user application flow.
The other answer to this question is that installing SSO enables your users to login multiple times without needing to enter a password (or authenticate) more than once. This dramatically decreases the UX (user experience) burden of multiple logins.
In some cases, “logging in” can even be completely automatic if the user has an active login session.
Check out the JWT recipe! Let me know your questions and concerns via firstname.lastname@example.org or by commenting on this post.