From the Trenches: OAuth 2.0 and the new SOBO

As many of our integrators are aware, Docusign has announced a deprecation plan, starting in September 2021, for our legacy authentication systems. This plan states that starting September 2021, new integrations are no longer able to pass the go-live process without using OAuth 2.0. Starting in September of 2022, all integrations in production will also be required to use OAuth 2.0.

One of the commonly used features with legacy authentication is SOBO, or “Send on Behalf Of.” In the Legacy authentication header itself, you could add a user by email address or apiUserName, and then have an envelope sent out specifically by that user while also not requiring them to provide their credentials to the application. While our legacy headers and even OAuth 1.0 mechanisms did support SOBO, our OAuth 2.0 methods do not. However, customers still need to be able to continue using their previous workflows, including the ability to impersonate a user. Enter: JSON Web Tokens (JWT).

JSON Web Tokens

JSON Web Tokens are a method of OAuth 2.0 that allows an integration to create tokens on another user's behalf. While SOBO allowed the envelope to appear to be sent by another user, when using JSON Web Tokens, the authenticated user and the sender really are the impersonated user. Here’s how it works:

1. An integration must be capable of applying an RS256 hash to a payload in order to create a JWT assertion. Docusign does not offer our own independent libraries for this; instead we recommend the use of standard dependencies that are tested throughout the industry.

2. A user must have consent provided for them. You can do this on an individual basis; or, if you have a claimed domain with users under said domain, you can grant blanket consent on their behalf.

Once consent is granted, your integration can freely generate OAuth tokens on behalf of that user, which allows you to authenticate as them and send envelopes just as they would have with SOBO.

Sounds great! How do I select a user to impersonate?

Like with SOBO, generally this workflow applies when users have a seat on the account the integration is connected to—meaning that you would be required to have access to their apiUserName or Email Address in order to impersonate them. With JWT, the link happens specifically by apiUserName; email addresses supplied in an assertion will not be recognized.

If the user has a seat on your account, then the matter is fairly straightforward: you make a GET request against the users endpoint, specifically searching by the user’s email address:

https://developers.docusign.com/docs/esign-rest-api/reference/connect/connectconfigurations/listusers/

The resulting call body will contain the individual apiUserName, which you then add in as the subject in your JWT assertion. This effectively targets that specific user and requests a token on their behalf. Once you have the apiUserName for that user, it should be cached so your application does not need to request it again.

Sounds interesting; but what if they’re not a member on my account?

That’s a good question, and the answer is a bit more tricky. If you don’t have someone’s apiUserName, then you will not be able to generate a token on their behalf, so the question becomes, “If someone is using my integration from a different account, how do I authenticate?”

There are two potential courses of action you can take to address this:

1. As part of the setup process.

   • Add the outside account admin’s apiUserName somewhere within your integration. If this user has granted consent, you can create a JWT token on his behalf and then make the same GET request to the users endpoint, which will instead give the apiUserName of the user you’re going to impersonate outside of your account.

2. Use a combination of JWT and Authorization Code Grants.

   • Authorization Code Grants do not require an apiUserName; instead, the user is required to log in at the start of their session. Once the user has logged in, a Bearer token will be returned to your integration. With said Bearer token, you can make a UserInfo call to request the user’s apiAccountId and BaseUrl (account ID and the server the account is located on), then make the same GET request to the users endpoint. This will accomplish the same goal, and will not be reliant on knowing the outside account's userIds.

In Conclusion

SOBO was a widely used feature with our legacy authentication system. While we don’t presently have a 1:1 alternative to SOBO with our new OAuth systems, we do have a few available options for you. If you need help getting this up and running, feel free to reach out to Support, myself or someone from my team would be happy to assist you.

Additional resources

• Docusign Developer Center

• @DocuSignAPI on Twitter

• Docusign for Developers on LinkedIn

• Docusign for Developers on YouTube

• Docusign Developer Newsletter