Edit

Develop your Office Add-in to work with ITP when using third-party cookies

  • Article

If your Office Add-in requires third-party cookies, those cookies are blocked if the Runtime that loaded your add-in uses Intelligent Tracking Prevention (ITP). You may be using third-party cookies to authenticate users, or for other scenarios, such as storing settings.

If your Office Add-in and website must rely on third-party cookies, use the following steps to work with ITP.

  1. Set up OAuth 2.0 Authorization so that the authenticating domain (in your case, the third-party that expects cookies) forwards an authorization token to your website. Use the token to establish a first-party session with a server-set Secure and HttpOnly cookie.
  2. Use the Storage Access API so that the third-party can request permission to get access to its first-party cookies. Current versions of Office on Mac and Office on the web both support this API.

    Note

    If you're using cookies for purposes other than authentication, consider using localStorage for your scenario.

    However, note that starting in Version 115 of Chromium-based browsers, such as Chrome and Edge, storage partitioning is being tested to prevent specific side-channel cross-site tracking (see also Microsoft Edge browser policies). This means that data stored by storage APIs, such as local storage, are only available to contexts with the same origin and the same top-level site. To work around this, in your browser, go to chrome://flags or edge://flags, then set the Experimental third-party storage partitioning (#third-party-storage-partitioning) flag to Disabled.

The following code sample shows how to use the Storage Access API.

function displayLoginButton() {
  const button = createLoginButton();
  button.addEventListener("click", function(ev) {
    document.requestStorageAccess().then(function() {
      authenticateWithCookies(); 
    }).catch(function() {
      // User must have previously interacted with this domain loaded in a top frame.
      // Also you should have previously written a cookie when domain was loaded in the top frame.
      console.error("User cancelled or requirements were not met.");
    });
  });
}

if (document.hasStorageAccess) { 
  document.hasStorageAccess().then(function(hasStorageAccess) { 
    if (!hasStorageAccess) { 
      displayLoginButton(); 
    } else { 
      authenticateWithCookies(); 
    } 
  }); 
} else { 
    authenticateWithCookies(); 
}

About ITP and third-party cookies

Third-party cookies are cookies that are loaded in an iframe, where the domain is different from the top level frame. ITP could affect complex authentication scenarios, where a pop-up dialog is used to enter credentials and then the cookie access is needed by an add-in iframe to complete the authentication flow. ITP could also affect silent authentication scenarios, where you have previously used a pop-up dialog to authenticate, but subsequent use of the add-in tries to authenticate through a hidden iframe.

When developing Office Add-ins on Mac, access to third-party cookies is blocked by the MacOS Big Sur SDK. This is because WKWebView ITP is enabled by default on the Safari browser, and WKWebView blocks all third-party cookies. Office on Mac version 16.44 or later is integrated with the MacOS Big Sur SDK.

In the Safari browser, end users can toggle the Prevent cross-site tracking checkbox under Preference > Privacy to turn off ITP. However, ITP can't be turned off for the embedded WKWebView control.

Google Chrome is phasing out 3rd party cookies in 2024 and introducing a feature named Tracking Prevention. If Tracking Prevention is enabled in the Chrome browser, your add-in will not be able to use any 3rd party cookies. Your add-in may encounter issues when authenticating the user, such as multiple sign-on requests, or errors.

For improved authentication experiences, see Using device state for an improved SSO experience on browsers with blocked third-party cookies.

For more information about the Google Chrome rollout, see the following resources:

See also