Using the OAuth JWT Flow - New Recipe Available
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:
