Secure programming practices: Lock down your Sender view!
Our customers over the years have found numerous uses of our APIs for a variety of purposes, one of which is the ability to work with the DocuSign system without having to necessarily leave the application or UI with which the potential sender or recipient is interacting. We have three types of tokens for this purpose: The Console view, which loads the inbox and management screens for a user; the Recipient view, which enables you to route a signer to their signing session without needing a DocuSign account, or if you don’t want them receiving email notifications; and lastly, there is the Sender View, which enables you to embed the recipient routing and tagging screens that you would normally interact with while creating your envelope. The focus of this post is to identify and mitigate a serious security issue related to using the Sender view.
The issue
The concept of a Sender view is essentially to create a URL that enables a user to access the recipients and tagging section of the DocuSign web UI. While the idea of using a Sender view can be beneficial in terms of allowing a user to tag a document, for example, without needing access to the account, Sender views do come with their own potential risks and drawbacks.
It’s important to understand how authentication works in terms of the various DocuSign tokens. When you generate an OAuth token, you are generating that token for a specific user and that user’s accounts. When you create one of the senderViewTokens, you need to remember that the user that you’ve authenticated as for making your API calls is the same user that is working on and sending the envelope. This may not seem important until you also realize that same token also has the potential to give access to anything else that the authenticated user can access. So, if your user is an Administrator and they are able to relocate to your inbox and management screens, they would have access to the same envelopes and settings as the user you’ve authenticated as. This can happen if a user has access to the browser’s Back button, can discard an envelope, hit Save and Close, etc.
From a security perspective, this is a major concern. If you have a look the DocuSign API reference guide, we actually outline this concern towards the bottom:
Information security notice: This method provides full access to the sending account. When you use this view, the current user has full access to the account. If the account has administrative privileges, then this method also provides administrator access. [emphasis added]
If your use case needs to enable a sender to update a draft envelope before it is sent or make other changes, take one of the following steps:
- Configure each sender to have their own individual user account to use this API method.
- Enhance your API integration so that this method is not needed. Your integration can create the tabs, recipients, and other envelope settings as needed.
Now that I’ve sufficiently alarmed you, let’s talk about mitigation.
Mitigation steps
Option 1: Lock down your sending session
As an enhancement to mitigate the risk of these tokens, DocuSign has implemented a number of optional URL parameters. You can see a general outline in the EnvelopeViews: createSender API Reference page.
The way this works is that, after the request for the senderViewToken is processed and receives the URL, you need to append these parameters onto the token itself, not the request for the token.
For example, the token sent back from a successful senderView request would be structured similar to this:
https://demo.docusign.net/Member/StartInSession.aspx?StartConsole=1&t=f514d53e-xxxx-b087-ba933cd11d1c&DocuEnvelope=766e59ff-xxxx-xxxx-xxxx-b7729bbe7e7e&send=1
If I open the original link, I see the normal features that I would expect during a signing session. Notice I have multiple Back buttons, Discard, Save and Close, and more.
Next, I’m going to generate a new sending session token and append to it some optional parameters. For this example I’m going to add in:
&backButtonAction=redirect&
showBackButton=false&
showHeaderActions=false&
showDiscardAction=false
When I use the new token with these parameters added, my session looks like this:
Notice the options I had before, to discard or go back, have been removed, and should I find a way to trigger the back button, the optional URL parameter would send me to the redirectUrl I supplied when I created the token.
Note: You should always supply a redirectUrl if you do not plan on giving the user interfacing with the Sender view access to the rest of your accounts.
Option 2: Do not generate a senderViewToken for a user with Admin rights
If the session is not properly locked down, there is a potential for the user to gain access to your home screen. Should that happen, this user would have access to anything the user you authenticated as would be able to see. If they have shared folders or admin credentials, this could potentially include other users’ contracts and send items, and even the account’s settings themselves. Creating these tokens under a non-admin user will mitigate the risk to someone accessing your account settings.
Note: The minimum required permission for this workflow will be the equivalent of DS Sender.
Option 3: Separate your responsibilities
If you’re planning on using these tokens with an authorized account member that should retain access to what they would normally see, give each user their own user seat. If they’re properly configured, no user should be able to access the envelopes or contracts of another user, as they would only be able to access what they would normally see as the authenticated user.
If you’re not planning on giving the users dedicated user seats, what you should do instead is utilize Envelope Custody Transfer rules. You can configure these rules to change the ownership of an envelope on send to another user that could potentially serve as a repository. Should the individual interacting with the Sender view manage to access the inbox of the account, any envelopes that were created via that user would have been transferred to the one acting as a repository. As far as the end user can tell, the Sent folder would be empty.
Option 4: Consider free-form signing
If your intention is to have the recipient tag their own documents, consider using free-form Signing instead. Free-form signing requires that Document Visibility be disabled for your account or you will receive an error message when creating an envelope due to a recipient not having tabs. When free-form signing engages, the user is sent to a signing session with tabs on the left that they can then drag directly over and place where they would like for them to go. Note that not all tabs are available in this system, so you’ll want to test first to make sure this is going to suit your needs.
Free-form signing can also lead to incorrectly tagged or "not in good order" envelopes. If at all possible, you'll want to look into ways the envelope can be pre-tagged for the recipient.
Conclusion
Sender views can be a very handy functionality to use, as long as you’re aware of the potential hazards that go along with using them. If you’re planning on using a Sender view as part of a standard workflow with a user that does not exist on your account, we would strongly recommend taking steps to safeguard your system. If you have additional questions, or if you’d like to request more information or clarifications, please reach out to Customer Service via the Support Portal. I or another member of my team would be happy to follow up with you.
