Creating SharePoint Add-ins that use the cross-domain library
There are some scenarios in which neither the low-trust nor the high-trust authorization systems can be used by a SharePoint Add-in, or they are not a good choice as the only means for the add-in to gain authorization to SharePoint resources.
The remote components of the SharePoint Add-in are not on-premises, but a corporate firewall blocks server-to-server communication between SharePoint and ACS, thereby preventing the use of the low-trust system.
Understand the architecture of the cross-domain library
The SharePoint cross-domain library is contained in the file SP.RequestExecutor.js, which is located in the /_layouts/15/ virtual folder of every SharePoint website. The scripts in this file encapsulate a secure well-known technique for overcoming the browser's restriction on cross-domain scripting: an iFrame can communicate with its parent page by means of the
window.postMessage() function, even if the page in the iFrame is in a different domain. So data requests and responses are passed over the domain boundary by using calls to
postMessage() function works only on browsers that support HTML 5, so SharePoint Add-ins that use the cross-domain library will not work on older browsers.
For SharePoint, the cross-domain library is loaded on a page of the remote web application where it creates a hidden iFrame that hosts a special proxy page from the SharePoint domain. The proxy page already exists on every SharePoint website.
postMessage(). On the proxy page, where the library is also loaded, the JSON object is parsed and reconstructed as a REST call to SharePoint. Because the proxy page is in the SharePoint domain, the browser allows the call.
Of course, the remote components of the SharePoint Add-in still have to have authorized access to the SharePoint resources. There are two ways to do this:
Set the add-in principal type to RemoteWebApplication (the default for provider-hosted apps) in the add-in manifest. When the add-in is registered with ACS, the registration includes the domain of the remote web application. SharePoint trusts domains that are registered with ACS, even though it is not, in this scenario, using any of the token passing flows that are part of the server-side low-trust system. For detailed information about registering add-ins, see Register SharePoint Add-ins.
In a SharePoint-hosted add-in, you can leave the add-in principal type set to its default, which is Internal. You can then set the AllowedRemoteHostUrl attribute of the Internal element to the URL of the remote web application, as in the following example.
<AppPrincipal> <Internal AllowedRemoteHostUrl="https://example.com/Home.html" /> </AppPrincipal>
For details on how to use the library, see Access SharePoint data from add-ins using the cross-domain library.
Access remote data from a SharePoint page
For details about how to use the library in this way, see Create a custom proxy page for the cross-domain library in SharePoint.