We have attempted to have an in-depth understanding of how permissions work in SharePoint add-ins in a blog post here and have mentioned a thing or two about the need for the cross-domain library when doing cross-domain calls.

When you have for example built an app where you would like to make calls to the host web, where the app is installed and which is outside the scope of your app, one thing to remember is that you will be subjected to cross-domain call and there are certain restrictions in place. This is basically due to security reasons. Browser protects any event of cross-site scripting and strictly dictates that client code will only be able to access data from within the same URL domain. Lucky for us SharePoint developers, to allow these domain calls, we can use SharePoint’s cross-domain library.

It is technically possible to have these cross-domain problems solved using our own custom code, but SharePoint already provides a robust and secure library that we, app developers, can take advantage of. Cross-domain library is a JavaScript file (SP.RequestExecutor.js) that allows add-in pages access data in the SharePoint domain. It is designed to solve above scenarios. One question you might have is that if cross-domain calls are restricted on different URL domains, how does the cross-domain library able to bypass this?

If you notice, every time an app is installed, a dynamic endpoint is also created which has its own domain. This dynamic endpoint is what we refer to as the app web and usually contains artifacts deployed to SharePoint such as a page, a list, etc.. The cross-domain library then creates a hidden iframe. The app page includes the cross-domain library, SP.RequestExecutor.js, that wires the remote page with a proxy page on the app web. The library loads the proxy page and uses the postMessage method to relay calls on the client side which in turn allows to make secure calls to SharePoint.

For SharePoint, cross-domain calls are supported on SharePoint-hosted, Provider-hosted and AutoHosted apps. SharePoint determines if it can trust the external domain via the AppManifest.xml in SharePoint-hosted apps. Through this file, domains that needs to be trusted through the internal app principal. While on Provider-hosted apps, SharePoint trust the domain that has been registered as part of the OAuth registration. Registration of the dynamically provisioned Azure website are automatically taken care of on autohosted apps so the library can be used without extra steps.

We basically just covered when we can use the cross-domain library as well as the reason why we need to use it. We will be tackling the actual usage of the cross-domain library and coding it in action on the next blog post.