Work with the cross-domain library across different Internet Explorer security zones in apps for SharePoint

apps for SharePoint

Learn how to use the cross-domain library in SharePoint 2013 when the host web and app pages are in different security zones in Windows Internet Explorer.

Last modified: March 09, 2015

Applies to: Office 365 | SharePoint Add-ins | SharePoint Foundation 2013 | SharePoint Server 2013

Note Note

The name "apps for SharePoint" is changing to "SharePoint Add-ins". During the transition, the documentation and the UI of some SharePoint products and Visual Studio tools might still use the term "apps for SharePoint".

If you are using the SharePoint 2013 cross-domain library for your apps, you should be aware of how security zones work in Internet Explorer. Your app may encounter some communication issues if the SharePoint website and the app are in different zones. This article explains what happens when you use the cross-domain library in different Internet Explorer security zones.

For security reasons, Internet Explorer prevents pages that are on different integrity levels (also known as security zones) to share cookies because each integrity level has its own cookie store. The integrity level of a page is determined by its top-most page, and any frame within that page will share the same integrity level. For more information, see Beware Cookie Sharing in Cross-Zone Scenarios.

The SharePoint cross-domain library uses a hidden IFrame and a client-side proxy page hosted on SharePoint to enable client-side communication using JavaScript. The cross-domain library is available when you reference the sp.requestexecutor.js file in your pages. For more information, see How to: Access SharePoint 2013 data from apps using the cross-domain library.

When the remote app page and SharePoint website are in different security zones, the authorization cookies cannot be sent. If there are no authorization cookies, and the IFrame tries to load the proxy page, it will be redirected to the SharePoint sign-in page. The SharePoint sign-in page cannot be contained in an IFrame for security reasons. In these scenarios, the library cannot load the proxy page, and communication with SharePoint is not possible.

The following diagram shows a cross-zone scenario in which the proxy page cannot be loaded. The top page puts the frame in the same security zone as http://remoteserver/remotepage.html. The proxy page does not load.

Figure 1. Cross-zone scenario where the proxy page cannot be loaded

Cross-zone scenario, proxy page cannot be loaded

The following are some examples in which the cross-domain library may not be able to load the proxy page:

  • Your customers are using SharePoint Online, and your remote app page is hosted on an intranet server. This scenario is prone to the proxy page loading issue because the SharePoint Online URL is not usually in the Local intranet zone. This is a very common scenario during initial development of an app because you may be using IIS Express or another local server to host your page without a fully qualified internet domain.

  • Your customers are using SharePoint on-premises with forms-based authentication, and your remote page is hosted on a cloud service (for example, Microsoft Azure).

There are a couple of ways to solve this problem during both app development (strongly recommended) and app run time.

Best practice: Use the apphost pattern

To handle a cross-zone scenario, we recommend that you have an apphost page in SharePoint. The apphost page is a SharePoint page that contains the remote page in an IFrame. Everything inside the IFrame in the apphost page exists in the same security zone as the app web. The cross-domain library in the remote page can receive the authorization cookies and loads the proxy page successfully.

The following diagram shows a cross-zone scenario being handled by using the apphost page pattern.

Figure 2. Cross-zone scenario handling by using the apphost page pattern

Cross-zone scenario handling by using the apphost

The code required for the apphost page is simple. The main portion of the apphost page is an SPAppIFrame element. You must use CSS to make the IFrame invisible so that it doesn’t interfere with your app.

The following markup is an example of a simple apphost page. The markup performs the following tasks:

  • Declares directives needed when using SharePoint components.

  • Declares styles to make the IFrame invisible.

  • Declares the SPAppIFrame and sets the target to the app start page.

<%@ Page 
    Inherits="Microsoft.SharePoint.WebPartPages.WebPartPage, Microsoft.SharePoint, Version=, Culture=neutral, PublicKeyToken=71e9bce111e9429c" 
    language="C#" %>
<%@ Register 
    Assembly="Microsoft.SharePoint, Version=, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<%@ Register 
    Assembly="Microsoft.SharePoint, Version=, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<%@ Register 
    Assembly="Microsoft.SharePoint, Version=, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>

    <title>Your app page title</title>
    <style type="text/css">
        html, body


If you want your users to deep link into portions of your app, your apphost page and the contents of the IFrame can collaborate to make that possible. One alternative is to use IFrame post-message communication and individual URLs per page in the remote app. To have individual URLs per page, you can create individual pages in the app web or use query string parameters on one page.

Alternative approach: Add the sites to the same security zone in Internet Explorer

If an app was not designed following the apphost pattern, you can still allow it to work by adding the following domains into the same security zone:

  • The domain of your SharePoint site (for example,

  • The domain of the cloud-hosted app (http://remoteserver).

  • The domain of Microsoft-hosted sign-in pages and services (*

Administrators can use Active Directory policies to push changes to all computers in the organization.

It is important to point out that the apphost pattern effectively puts your remote page in the same security zone as the app web. Make you sure you understand the implications of adding a site to a security zone. For more information, see How to use security zones in Internet Explorer.

Other browsers, such as Google Chrome, Mozilla Firefox, and Apple Safari, do not implement the concept of security zone. If a browser does not isolate the cookies in separated storage, it probably will not encounter the difficulties described in this article. We recommend that you follow the apphost pattern in your apps. Using the apphost pattern ensures that your app works in the mentioned browsers and Internet Explorer, regardless of which security zone SharePoint is in.

© 2015 Microsoft