Solving cross-domain problems in apps for SharePoint

Hello there, I’m Humberto Lezama-Guadarrama, Program Manager on the Office Developer Platform team. In this post I will analyze some of the challenges that developers will likely face when building apps for SharePoint and how our cross-domain library and APIs can help you solve them.

Cross-domain, the eternal challenge

Almost all web developers have at some point in their career faced cross-domain problems while building web apps. In a nutshell, you encounter these type of issues whenever an app wants to make client-side calls (for example, using JavaScript + XMLHttpRequest) from a page hosted in one domain (for example, to a page or service hosted in a different domain (for example, By default, browsers block this type of communication for security reasons; they don’t want malicious apps to grab data or execute code without users knowing it.

So, what’s the big deal? Well, the very nature of the new app model for SharePoint encourages developers to host code outside of SharePoint (see hosting options), which means that, by design, apps will face cross-domain challenges.  You can use server-side code + OAuth to avoid cross-domain issues (because the communication in that case is server-to-server), but what if you want to use JavaScript?  We all love JavaScript don’t we? 🙂

Cross-domain library for apps for SharePoint

There are many different techniques to overcome cross-domain issues in JavaScript, several of which are pretty hacky. The most robust solutions to date, that work in all major browsers, involve using the IFrame postMessage method to establish mutual trust between pages loaded from different domains. Technically, somebody writing an app for SharePoint could solve cross-domain problems on their own, but we wanted to provide a robust, secure library that app developers can take advantage of.

So, how does it work? The gist is that we take advantage of a really cool feature in apps for SharePoint named app webs. Essentially, every time an app is installed (and contains at least one artifact that is deployed into SharePoint, such as a blank page) a dynamic endpoint is created on the fly. This dynamic endpoint (the app web) has its own domain, which means that any client-side calls to it are automatically security trimmed so the app cannot ever elevate its privileges (and cause security issues).  What the cross-domain library does is that it creates a hidden Iframe that wires your remote page with a proxy page on the app web. We then use the IFrame postMessage method to relay the calls on the client side. This effectively enables you to securely make calls to SharePoint using JavaScript. Figure 1 summarizes this process.


Figure 1. Cross-domain library execution process


Wait a minute, but how does SharePoint know how to "trust" the external domain (for example, in the Figure 1)? The answer is in the type of hosting that you are doing; cross-domain calls are supported for all types of hosting:

  • For SharePoint-hosted apps, you declare which domain to "trust" by using an internal app principal; you do this in the AppManifest.xml. This sounds a bit counterintuitive right? Why would you use a SharePoint-hosted app if you are going to host pages outside of SharePoint?  Well, because you need the app web to communicate back to SharePoint. To create an app web you have to host "something" on SharePoint, even if it’s just a default page. You could of course also host more interesting things, like document libraries or lists, and use your remote page to access them.
    <AppPrincipal> <Internal AllowedRemoteHostUrl="" /> </AppPrincipal>
  • For provider-hosted apps, SharePoint trusts the domain that you register as part of your OAuth registration (even if you don’t actually use OAuth). Provider-hosted apps built for the marketplace use the seller dashboard to register their domain, as shown in Figure 2. For more details consult the guidelines for registering apps for SharePoint 2013.


Figure 2. Seller dashboard’s domain registration page

  • For autohosted apps, you don’t have to worry about it. We automatically take care of registering the dynamically provisioned Azure website so you can use our library without any additional registration.

Sounds a bit complex, huh?  Well, it kind of is under the hood. But, actually using the cross-domain library after registering your external domain is pretty easy. You just have to reference our JavaScript library and initialize it, and then you’re done.  Here’s a snippet:

// Load the cross-domain library. 
$(document).ready(function () { 
  var hostweburl; 
  var appweburl; 
  //Get the URI decoded URLs. 
  hostweburl = decodeURIComponent( getQueryStringParameter("SPHostUrl") ); 
  appweburl = decodeURIComponent( getQueryStringParameter("SPAppWebUrl") ); 
  // Load the .js files using jQuery's getScript function. 
    hostweburl + "/_layouts/15/SP.RequestExecutor.js",
  // After the cross-domain library is loaded, execution 
  // continues to this function. 
  function continueExecution() { 
    var executor; 
    // Initialize your RequestExecutor object. 
    executor = new SP.RequestExecutor(appweburl); 
    // You can issue requests here using the executeAsync method 
    // of the RequestExecutor object.
  // Function to retrieve a query string value.  
  function getQueryStringParameter(paramToRetrieve) {
    var params = document.URL.split("?")[1].split("&");
    var strParams = "";

    for (var i = 0; i < params.length; i = i + 1) {
      var singleParam = params[i].split("=");
      if (singleParam[0] == paramToRetrieve)
        return singleParam[1];


We have a detailed how to article that explains the cross-domain library and several samples for you to try right away. You might be pretty surprised about how quickly you can put something together.

Important Note: You may also face some challenges with Internet Explorer security features that prevent cross-internet zones from sharing cookies. The way this manifests itself is that the cross-domain library fails to load and you always get an error.  Solving this problem is pretty straightforward—the details of the issue and the resolution are documented in this article.

Cross-site collection calls

A different problem that is often lumped into the same cross-domain category is issuing calls to SharePoint across sites or across site collections. For example, an app installed at wants to retrieve a list from

On the surface this looks like a cross-domain problem, but it is not. It’s actually a traversal problem inside SharePoint resources.  What you really want is for your app to talk to your allowed endpoint (your app web) and from there you want to internally proxy the call to a different site collection.

So, does that mean that you are out of luck if you want to use JavaScript?  Nope, we actually have a pretty handy object for you named AppContextSite.  All you have to do is set AppContextSite to point to the target web you want to talk to. Please note that in order for cross-site collection calls to work your app must be deployed as a tenant scoped app by an administrator; this is currently a security restriction of the API. Here is the syntax:



var ctx = new SP.ClientContext(appWebUrl);
var appContextSite = new SP.AppContextSite(ctx, targetUrl);


var ctx = new SP.ClientContext(
); //Get this from tokens instead of hardcoding it. var appContextSite = new SP.AppContextSite(
); //Get this from user input or context tokens. ctx.Load(appContextSite.get_web());





Full URL Example:’’


Wow, that is a lot of info right? In practice though, it is pretty straightforward after you learn how the pieces fit together. In the vast majority of cases all you have to do is reference our cross-domain library and use it and you are good to go. If you do encounter issues, we are monitoring our support forums so feel free to ping us.

Happy coding!

Comments (41)

  1. Jonty Chickweed says:

    What is the interplay here with Azure AD?  What if I write an app that is pulling content from a 3rd party solution that uses Azure AD for authentication.  What happens when the app is rendered inside of SharePoint Online?  What authentication is happening behind the scenes?  Does the session I have in IE pass through to the app, or is there another authentication that happens behind the scenes?

  2. Jonty,  the techniques I described here allow your app to talk to SharePoint, there is no interplay with Azure AD.

  3. in the target site collection the app says:

    in the target site collection the app try to access, how does it configure to allow the app to access the site collection?, or does it use the user's access to determine the access to target web?

  4. Bob Kiefer says:

    Humberto, does this work with SharePoint 2010?

    I have an ASP.NET application on one web server, and I want it to access SharePoint (on another server) programmatically, to store and retrieve Excel and PDF documents.

    Both servers are in the same internal network, but they a in different Windows domains.

  5. Parham says:

    Humberto, just wanted to thank you for your fantastic article. very well written and informative. I loved this article 🙂

  6. Steffen Schindler says:

    I'm trying to get some data from an other site collection than the hostweb using a sharepoint hosted app. I've tried your REST- and the JSOM-example above. But none of it works. This article on Sharepoint.Stackexchange declares the same problem (…/accessing-another-site-collection-from-a-sp2013-app). Do you have any advice?

  7. Harpreet says:

    Humberto, does this work for Outlook mail app.

  8. prabavathi says:

    cross domain in .net is working fine. but not wit share point. could u pls tell me the steps how can i proceed furthur…

  9. Steffen, please note you need the app to be deployed as tenant scoped by an admin. This is currently a restriction of the API. The article has been updated to clarify this behavior.

  10. Harpreet, depends on what you mean by "works" on a mail app 🙂  The library works on any webpage that talks to SharePoint as long as there is a corresponding SP app installed on the target (so it opens up the appweb). So if your mail app is reading information from SP, yes, you can use this library for that. If what you mean is using the library to talk to other services (not SP) then nope, it wasn't designed for that. Thanks!

  11. Bob, this library only works with SharePoint 2013

  12. Parham, thank you, glad you liked the article 🙂

  13. King says:

    Hi, the full URL Example link is not working

  14. SharePoint app is not redirecting to app domain says:

    I have configured app domain and able to ping also . I have configured the app management and subscription setting service applications . I have configured the App Catalog URL also .

    After deploying the sharepoint app in to the app catalog site , I am facing the below issue.

    The host name resolution (DNS lookup) for this host name ( ) has failed. The Internet address may be misspelled or obsolete, the host (  ) may be temporarily unavailable, or the DNS server may be unresponsive.

    Please check the spelling of the Internet address entered. If it is correct, try this request later.

    Please help to solve this issue

  15. Tudor Iliescu says:

    Is it possible to access a SharePoint custom web service from a SharePoint-hosted app within the same farm? I get an 'unauthorized' response. If I call an external web service such as…/Categories the call is done successfully. We need to get some data (from host web) in elevated privileges, data which is displayed inside our app. Another thing we tried is to call a custom aspx from the host web in order to return some json. Neither approach is working and I can't find any solution to this problem. Is this possible, to somehow access host web data in elevated privileges from a SP-Hosted app? (I don't want to make the app a provider hosted app)

  16. Garima says:

    Hi Humberto,

    Thanks for the great article.

    You have mentioned that in javascript, app has to be deployed at tenant level for it to work. But the tenant level app share the same web. isn't it? So this is a restriction for now?


  17. Tolga says:

    As you gave as an example at the end of the article, I use REST query to get the items from a list in another site collection.


    I changed the app permission as follows.


       <AppPermissionRequest Scope="http://sharepoint/social/tenant&quot; Right="Write" />

       <AppPermissionRequest Scope="http://sharepoint/search&quot; Right="QueryAsUserIgnoreAppPrincipal" />

       <AppPermissionRequest Scope="http://sharepoint/content/tenant&quot; Right="FullControl" />

       <AppPermissionRequest Scope="http://sharepoint/content/sitecollection/web&quot; Right="FullControl" />

       <AppPermissionRequest Scope="http://sharepoint/content/sitecollection&quot; Right="FullControl" />


    If I run the application, I got an access error.

    What do you mean exactly with that point "app must be deployed as a tenant scoped app by an administrator"?


  18. Parthasarathy S says:


    Thanks for the article. I tried this using provider hosted app and got this error..any clue?

    "Your domain doesn't match the expected domain for this app deployment."



  19. Manuel says:

    how about /_api/contextinfo?

    if I need get the Form Digest Value, can I use the current contextinfo or I need to get it from "the other site"?

  20. Garima, a tenant scoped app can have access to more than one site collection

  21. Tolga, tenant scope != tenant level permissions (I know it can be confusing). The app must be installed by an admin as a tenant scoped app:…/fp179896.aspx

  22. Parthasaranthy, double check your domain matches your app.…/jj687469(v=office.15).aspx  The error is telling you that the app domain isn't the one that is registered with SP.

  23. Manuel, not sure exactly how/where you are using that info but my guess is that you can just query that from the appweb itself; no need for a cross-domain call.

  24. Raghu says:

    Hi, Im getting following error message in safari browser when the app is launched modal dialog. The app works fine in full window mode.

    Blocked a frame with origin "; from accessing a frame with origin ";. Protocols, domains, and ports must match. (x3).

    Is there anything i need to change in browser settings or can it be fixed in code?

    Please help

  25. Shlok chakankar says:

    Could you elaborate how we can use REST and JSOM in provider hosted app where we are using server to server authentication.

  26. Karman says:


    Is it possible to get the cross site collection in sharepoint hosted app using sharepoint Client Object Model. we are using the sharepoint 2013 online.

    ClientContext sourceClientContext = TokenHelper.GetClientContextWithAccessToken(currentWebURL, appOnlyAccessToken);

                   if (sourceClientContext != null)


                       Web objSite = sourceClientContext.Web;


                       sourceClientContext.Load(objSite, w => w.Title, w => w.Url, w => w.AssociatedOwnerGroup);



    But unable to use  AppContextSite.

    Please Help

  27. Ricardo Loo says:


    The cross-domain library is designed to be used with JavaScript. If you're using the .NET client object model you should probably use OAuth instead of the cross-domain library.


  28. Fernando says:

    I am creating a web site that leverages sharepoint apis. I am running into issues with 401 errors unless I do a NTLM auth in Javascript. How do I avoid having to auth every time. Is there a way to get a cookie

  29. Philip says:

    Why the "remote hosted" chose AppWebProxy.aspx from the "app web" not from the "Host web" directly, since the "iframing" can surpass clients calls through different domains ?Why use of the "app web" as an intermediary?

  30. NGKPrasad says:


    thanks for the information,  I have  query, please help

    I have app web hosted in my local system and my app got deployed in Server 1( SharePoint server). I have created a user in Server, when I am logging with new user in my local machine, app is not accessible and throwing an error "The remote server returned an error: (401) Unauthorized."

    permissions given to server 1 admin but not able to give for the new user created.

    identification :

    1. Domain names both are different ( local system domain is different from the server 1)

    please help in this

  31. NGKPrasad says:

    sorry to mention the permission given in my local hosted application, as it hightrust provider hosted app

  32. Mihir says:

    Thank you so much. It was really helpful. I am trying to connect to the My Sites of current user. Your article was great.

  33. Ricker Silva says:

    Humberto, This is quite a good article but Ithink I don´t get it through. I have a two views MVC site right now as a provider hosted App. A few days ago I have a direct link from una view to another and it worked good. Nos I added some code retrieving information from SP context before making the call to the other view. And I got a message that the content can not be displayed in the iframe. it Works if it is full screen.

    However I noticed that when the app is loaded there is a querystring variable that has the sharepoint host information, and it is lost once I click the link.

    Is this behavior somewhat related to this crossdomain? I´m gonna try any way, but I don´t know how to debug it, the seller dashboard is only for deployed apps, how can I be sure it is good before release? during debug?


  34. achu says:

    Is cross domain data transfer possible using CSOM-javascript

  35. Sandip Patil says:


    In my organisation we have different web applications for departments like HR, Finance, Billing, Support etc. There are many site collections inside every web applications.

    Now we have to create an Apps so we can show data from any web applications to any other web applications. Say i have Employee Leaves list on one of the site collection on HR web appln, now i want to show this list data on Finance or Billing sites.

    What type of apps i should use here?

    How to access data across web applications in apps?

  36. Syed Musthafa says:


    We have two site collections, application site and my site.

    We need to access list items/library files like (.js/images) from application site in my site for branding it.

    Is any way to get list items, we tried listdata.svc/REST api – gives access denied error

    Note: we not developed SP app, just using js coding

    thanks in advance

  37. Ankur Garg says:


    I am trying to access the BCS list (created thorugh farm level external content type) residing in host web from sharepoint hosted app but not able to. Unauthorized error coming up. Please assist. I am using cross domain library with rest. Can we do this. and how. Please assist


  38. Morris says:

    I'm in the same boat as Syed.  We need to access lists in the Host from the My Site.  Microsoft has recommended that the My Site be deployed to its own Web App and therefore has a different domain.  How would I implement the cross site library in such a case.


           url: MySiteURL + "/_api/SP.AppContextSite(@target)/web/title?@target='" + hostweburl + "'",

           method: "GET",

           headers: { "Accept": "application/json; odata=verbose" },

           success: successHandler,

           error: errorHandler


    This is returning an error :  "{"error":{"code":"-1, Microsoft.SharePoint.SPException","message":{"lang":"en-US","value":"There is no app context to execute this request."}}}"

  39. Dipal Bhavsar says:


    Would you please help in my scenario?

    I want to host my SharePoint App (either SharePoint hosted or Provider Hosted) which access custom lists data from particular SharePoint site as…/sitecollection

    Which approach I need to consider.

    Please Guide

  40. Dipal Bhavsar says:

    Please consider this App is required to available at SharePoint Store 365 environment.