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 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’ve 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. 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 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.
To stay up-to-date, we encourage you to follow the Office Add-ins developer blog.
Light
Dark