Microsoft 365 Office Add-ins

Action required: Update your Office add-in dialog for cross-domain communication

We have recently implemented a security update to the Office add-in Dialog API that affects cross-domain communication between the dialog and the parent page (typically a task pane) using either the Office.ui.messageParent or Office.dialog.messageChild methods. Cross-domain communication means that your add-in calls one of these methods when the parent page and the dialog are in different domains.

If you are using either method to make cross-domain calls, this is a breaking change. You must update your add-in. You need to add a new parameter, DialogMessageOptions, to the call of messageParent or messageChild. The new parameter is an object with a targetOrigin property that specifies the URL of the domain for which the message is intended.

For more information and sample code, see Cross-domain messaging to the host runtime  and Cross-domain messaging to the dialog runtime.

Same domain communication will remain unaffected. A call to messageParent or messageChild does not need the new parameter when the dialog and parent are in the same domain, so you don’t need to do anything if your add-in only makes same domain calls.

This change does not affect the Office add-in single sign-on API (Office.auth.getAccessToken).

As part of this change, we have introduced a new requirement set, DialogOrigin 1.1, which contains the new versions of messageParent and messageChild.

On Windows, users can set a registry key to bypass the target origin validation if needed. (For instructions, see the Tip in Cross-domain messaging to the host runtime.) Doing so allows add-ins making cross-domain communication to continue running even if they haven’t been updated to use the new parameter. You should have users do this only as a temporary expediency until the add-in is updated.

Call to Action

If your add-in makes cross-domain calls of messageParent or messageChild:

  • As soon as possible, update your add-in to pass the new parameter.

Changes are rolling out with the following builds:

  • Office on the web: Live from 7/19/2021
  • Microsoft 365 on Windows subscription: 16.0.14310.10000
  • Office on Mac: 16.52.21080801
  • Office on iOS: 2.52.21080801
  • Semi-annual channel: The September Patch Tuesday (9/14/2021) will include the update.
filter-icon