Action required: ensure your Microsoft Teams apps are ready for upcoming domain changes
In April 2023, Microsoft announced that it would be undertaking a multi-year effort to reduce domain fragmentation among authenticated, user-facing Microsoft 365 apps and services by bringing them onto a single, consistent and cohesive domain: cloud.microsoft. This consolidation will help improve security, administration, and user experience across the board, and will ultimately lay a foundation for better and tighter integration across the Microsoft 365 ecosystem.
As we prepare to migrate the Teams, Outlook, and Microsoft 365 web apps to the cloud.microsoft domain, developers of Teams apps – including those that run on Outlook and Microsoft 365 – need to take the actions described below to ensure that those apps continue to function on the new domain. If no action is taken, your app may not render in the new domain (teams.cloud.microsoft) when it goes live in June 2024. If you are unable to update your app before that time, any tenant running your app will remain on teams.microsoft.com while we work with you to make the necessary changes.
This change impacts embedded applications where an external web app is rendered inside Teams, Outlook or Microsoft 365. If your app falls into this category, it will be affected.
How to prepare your app for cloud.microsoft
Today, apps that embed their web content in a Microsoft 365 host application such as Teams, Outlook, or Microsoft365.com run on a set of inherently trusted domains that are hardcoded in the TeamsJS client library. To support the rollout of applications under cloud.microsoft domain and make future cross domain app integration more seamless, Microsoft will migrate this list of trusted domains to a new CDN endpoint to be called on app initialization. This change was released in early January 2024 as part of Teams JS version 2.19 release. This new list will be dynamic, which will limit the impact of any future domain changes on your app.
To avoid any breaking changes to your app in the new domain, you will need to perform the following actions:
- Upgrade Teams JS library to version 2.19 or higher.
- Update your x-frame-options/CSP headers to allow for the new domains. To ensure the app keeps working across existing and future Microsoft 365 hosts, please ensure to allow “*.cloud.microsoft”.
Timeline and impact:
To prepare your app for the transition to teams.cloud.microsoft, please complete the changes above as soon as you are able. The teams.cloud.microsoft domain is now available for testing, with full operation alongside teams.microsoft.com expected in June. At that time, the expected user experience will be as follows:
App opened in teams.microsoft.com:
- Everything will work as expected.
App opened in teams.cloud.microsoft:
- CTAs complete: Everything will work as expected.
- CTAs not complete: Error message given with guidance for the user to navigate to teams.microsoft.com to use the app.
The transition to cloud.microsoft will benefit users and developers across the Microsoft 365 ecosystem. We are excited to take the next steps toward bringing Teams, Outlook, and Microsoft 365 onto the unified domain, and extending those benefits to app developers as well.
More information
- Prerequisites | Microsoft Learn
- Extend a Teams personal tab app across Microsoft 365 – Teams | Microsoft Learn
- Introducing cloud.microsoft: a unified domain for Microsoft 365 apps and services – Microsoft Community Hub
Follow us on X (Twitter) / @Microsoft365Dev and subscribe to our YouTube channel to stay up to date on the latest developer news and announcements.
Light
Dark
10 comments
what does ‘CTAs not complete’ mean here ?
do we need to change teams manifest file too ?
The 2 CTAs being referenced are just above in the post:
1. Upgrade Teams JS library to version 2.19 or higher.
2. Update your x-frame-options/CSP headers to allow for the new domains. To ensure the app keeps working across existing and future Microsoft 365 hosts, please ensure to allow “*.cloud.microsoft”.”
So “CTAs not complete” means the app developer has not performed those two actions in order to be ready for this domain change.
do we need to add *.cloud.microsoft as valid domain in manifest.json ?
just realize “CTAs ” mean Calls to Action 🙂
No, you don’t need to make any changes to your manifest.
Any action items for Teams app built not with JS library but legacy Python SDK?
Hi Jie. Not sure what you’re referencing with “legacy Python SDK” as we don’t have a “python SDK” – but if you mean Teams JS v1, then in addition to the above noted CTAs you will need to update to Teams JS v2 as we will not be supporting the new domains on v1.
With this new migration , I have a question for simple tab apps built on react for teams , our app is launched directly from the URL we have given in the manifest json file , so where do we put the CSP headers , or , are they at all required for such use cases similar to ours ?
Hi Janit. CSP headers are not a requirement, but are strongly recommended as an added security measure to protect against CSS attacks. Where they go is a developer design decision but I believe many developers put them in an index.html file. You can read some additional information at these links:
https://learn.microsoft.com/en-us/microsoftteams/platform/m365-apps/extend-m365-teams-personal-tab?tabs=manifest-teams-toolkit
https://learn.microsoft.com/en-us/microsoftteams/platform/tabs/how-to/tab-requirements
https://staticsint.teams.cdn.office.net/evergreen-assets/safelinks/1/atp-safelinks.html
I am developing a Teams app using the TeamsFx library with .net core blazor app. I have updated the TeamsFx library to the latest version, but it internally loads Teams.js version 2.17, and I do not know how to update it ourselves.
TeamsFx Lib
We will update the dependency for this in TeamsFx during the next pre-release version coming soon.