The problems with iframes
Most developers, when creating their integration with DocuSign, will want to embed the signing experience into their application so that the user doesn’t need to navigate to DocuSign to sign an envelope. This helps keep the application simple for the signer and gives them a more user-friendly experience. The signing experience can be displayed in different ways for the end user, and one that I see sometimes is developers using an iframe. The allure of using an iframe is understandable: it seems to be a simple and straightforward way to display the signing experience. However, using iframes can also lead to many unforeseen problems and limitations that only crop up at a later date.
What can go wrong?
Using iframes to embed the DocuSign signing experience can lead to a number of issues:
Feature limitations: DocuSign offers certain features you may be interested in using, such as Identity Verification, that are not compatible with iframes. Further to this, the OAuth security standard prohibits the use of iframes as outlined in RFC 6819 § 4.4.1.9.
Iframe support changes: Iframe support from the browser vendors is constantly changing, and new security-related restrictions are being introduced on them all the time. Due to the ever-changing landscape surrounding iframes, a workflow you built yesterday may not work tomorrow because of new changes to iframes and how they operate.
Troubleshooting problems: Any time additional layers of complexity are added to a workflow, it increases the difficulty in finding the root cause of the problem, as there are multiple layers to peel back to find the root cause of the issue. In those instances during customer support sessions when I needed to assist in finding the root cause of the issue when using an iframe, I’ve always needed to decouple signing experience from the iframe to troubleshoot the issue, and most of the time the issue was indeed coming from the iframe itself.
Security concerns: There are a lot of causes for concern when using an iframe from the perspective of security as well: for instance, iframes allow for clickjacking; the user cannot see the DocuSign URL to know that the destination is correct; and your site becomes vulnerable to cross-site attacks.
Better alternatives
Instead of using an iframe for the sending and signing experience for your users, you should load the signing or sending experience in a new tab in the browser or redirect the browser to the URL and maintain state. By using either of these two methods, you’re mitigating the chances that your application will break due to unexpected changes that you cannot control, and you’re giving your users a more secure and trustworthy experience. Our React code example shows how you can perform both of these methods while using the OAuth authentication flow.
Opening a new browser tab
Browsers will allow a Javascript function to open a new tab on the browser if the Javascript was invoked via a user action (such as clicking a button or a link). The existing browser tab will continue to operate, but the browser will move the focus to the new tab. Once the signing ceremony is complete, the original tab can programmatically close the tab that it opened.
Pro tip: If you open the new tab to the DocuSign signing experience URL, then nothing will be shown in the tab until DocuSign responds. The blank screen won’t last long, but a better user experience is to eliminate it entirely. Here’s how: Open the new tab to a URL that your app controls. That page will display a loading graphic and redirect to the signing experience. The graphic will continue to be shown until it is replaced by the signing experience loading graphic.
