Update your Office Add-in Dialog for cross-domain calls
We’ve recently implemented a security update to the Office Add-in Dialog API. This 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.
Action required to update your Office Add-in Dialog
If you’re 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
messageChild. The new parameter is an object with a
targetOrigin property that specifies the URL of the domain for which the message is intended.
Same domain communication will remain unaffected. A call to
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’ve introduced a new requirement set, DialogOrigin 1.1, which contains the new versions of
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. Then, cross-domain communication will continue to run even if you do not update them 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
- 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.
To stay up-to-date, we encourage you to follow the Office Add-ins developer blog.