New browser security settings and iframes
Multiple browsers, including Chrome for desktop, Chrome for Android, Firefox, and Microsoft Edge, have updated or are planning to update their default for the Referrer-Policy HTTP header to the more secure strict-origin-when-cross-origin setting. Additional browsers are also expected to adopt this policy in the future.
As the new default policy setting is rolled out and customers update the browser on their computers, tablets, and phones, some DocuSign developers are discovering that their applications are no longer working properly, especially with some patterns of using iframes. This is because DocuSign uses the browser’s default referrer policy.
The new referrer policy primarily affects developers who are examining the referer header [sic] to check the event query parameter sent by DocuSign when an embedded signing ceremony is completed by the signer. (Yes, the header’s name should have been spelled correctly in the first place as the referrer header. But in the interests of backwards compatibility, the incorrectly spelled referer header remains.)
With the new setting for the Referrer-Policy header, the referer header no longer includes query parameters from the referring website.
Solving the problems
There are multiple layers to solving the problems the new browser policy exposes:
Don’t use an iframe
These days, especially for an embedded signing ceremony, iframes are rarely needed: they provide an inferior trust user experience, since the signer can’t see the DocuSign URL; they enable clickjacking; and they don’t support some important DocuSign features such as Identity Verification. Similar to the issues for using a DocuSign embedded signing ceremony, the OAuth security standard prohibits iframes. See RFC 6819 § 4.4.1.9.
Usually a better solution is either to redirect the browser to the signing ceremony’s URL, or to open a new tab in the browser for the signing ceremony. The new React code example demonstrates both techniques for handling its OAuth authentication flow.
If you do decide to use an iframe, set the iframe to use 100% of the screen’s width and height to minimize UX issues. This is especially important for applications that may be used from mobile or tablet browsers.
Don’t use the event query parameter for business decisions
As documented on the Developer Center and in the code examples, the event query parameter should not be used for business decisions, since it is not cryptographically signed and can be spoofed by a bad actor. Instead, to determine the status of an envelope or whether a particular signer has signed it or not, either look up the information from DocuSign using the API, or use an authenticated Connect webhook message from DocuSign. The event query parameter should only be interpreted as a hint about the signer’s action.
Note that webhook notifications should not be a UX blocker: don’t make your users wait until the webhook notification is received. But if you need to know the envelope’s status immediately, just call an appropriate DocuSign API: Envelopes: get, listStatus, or listStatusChanges.
Redirect the browser
Often, the easiest option is to have your application redirect the user’s browser to the DocuSign signing ceremony URL, and use your application’s URL as the returnUrl. Before doing so, your application should save any state information to the session storage of the web framework the application uses. You can also include an additional query parameter if needed by including it in the returnUrl: for example, apps.myCompany.com/app1?signingCeremonyReturn=1. When DocuSign redirects to your application, it will append the event query parameter to any existing query parameters in the URL.
Later, after the signer has finished with the signing ceremony, DocuSign will redirect to your application and will include the event query parameter. At this point, your application needs to determine if it is being invoked for the first time, or is being invoked after the signing ceremony. Your application should look up its state from the session storage, and then continue its flow now that the signing ceremony is done.
If needed, the DocuSign signing ceremony can ping your application (from the browser) to maintain the user’s session and state within your application while the signer is interacting with the signing ceremony. See the pingUrl and related attributes.
Use Window.postMessage
Another option: instead of the referer header, use Window.postMessage to communicate between either an iframe or a new browser tab and the parent browser tab that your application uses. This flow is demonstrated by the new React code example:
- When your application starts, it uses window.addEventListener to listen for messages. Here’s a code example.
- Later, your application creates a new browser tab (recommended) or an iframe and saves the resulting
windowobject in a variable. The initial web page URL is the URL for the embedded DocuSign signing ceremony. The returnUrl is not your application’s URL. Instead, it is an intermediate simple web page with a JavaScript program. That JavaScript program callsWindow.postMessageto send the query parameters (from the embedded signing ceremony) to the parent page (your application). Here’s a code example of an intermediate page. To send the query parameters, use window.location.search instead of the example’swindow.location.hash. - When the message is sent, your web page’s listener method receives and processes the message. Eventually it closes the tab that it had opened in step 2 by using the Window.close method on the child tab’s
windowobject saved in step 2.
Summary
Don’t use the referer [sic] header. Instead, there are multiple software patterns that will enable your application to use an embedded signing ceremony securely without an iframe (recommended) or with an iframe if necessary.
