Exchange user identity tokens and callback tokens are deprecated and will begin to be turned off in October 2024. We recommend moving Outlook add-ins that use legacy Exchange tokens to nested app authentication.
General FAQ
What is nested app authentication (NAA)?
Nested app authentication enables single sign-on (SSO) for applications nested inside of supported Microsoft applications such as Outlook. Compared with existing full-trust authentication models, and the on-behalf-of flow, NAA provides better security and greater flexibility in app architecture, enabling the creation of rich, client-driven applications. For more information, see Enable SSO in an Office Add-in using nested app authentication.
What is the timeline for shutting down legacy tokens?
The following tables list the key milestones based on which channel customers are using. Note that the general availability (GA) date for NAA will vary based on channel. We'll provide tooling for administrators to reenable Exchange tokens for tenants and add-ins if those add-ins aren't yet migrated to NAA.
Current Channel
| Date | Action |
|---|---|
| October 2024 | NAA is GA for Current Channel. Exchange online tokens are turned off by default for new tenants and existing tenants known not to be using Exchange tokens. The administrator can choose to reenable Exchange tokens on tenants or add-ins as needed. |
| January 2025 | Exchange online tokens are turned off by default for all tenants. The administrator can choose to reenable Exchange tokens on tenants and add-ins as needed. |
| June 2025 | The ability for the administrator to reenable Exchange online tokens is removed. If a tenant or add-in needs Exchange tokens reenabled, the administrator must contact Microsoft. |
| October 2025 | Exchange online tokens are turned off for all tenants and add-ins, including any that were reenabled. |
Monthly Enterprise Channel
| Date | Action |
|---|---|
| November 2024 | NAA is GA for Monthly Enterprise Channel. Exchange online tokens are turned off by default for new tenants and existing tenants known not to be using Exchange tokens. The administrator can choose to reenable Exchange tokens on tenants or add-ins as needed. |
| February 2025 | Exchange online tokens are turned off by default for all tenants. The administrator can choose to reenable Exchange tokens on tenants and add-ins as needed. |
| June 2025 | The ability for the administrator to reenable Exchange online tokens is removed. If a tenant or add-in needs Exchange tokens reenabled, the administrator must contact Microsoft. |
| October 2025 | Exchange online tokens are turned off for all tenants and add-ins, including any that were reenabled. |
Semi-annual Channel
| Date | Action |
|---|---|
| January 2025 | NAA is GA for Semi-annual Channel. Exchange online tokens are turned off by default for all tenants. The administrator can choose to reenable Exchange tokens on tenants and add-ins as needed. |
| June 2025 | The ability for the administrator to reenable Exchange online tokens is removed. If a tenant or add-in needs Exchange tokens reenabled, the administrator must contact Microsoft. |
| October 2025 | Exchange online tokens are turned off for all tenants and add-ins, including any that were reenabled. |
Semi-annual Channel Extended
| Date | Action |
|---|---|
| June 2025 | NAA is GA for Semi-annual Channel Extended. The ability for the administrator to reenable Exchange online tokens is removed. If a tenant or add-in needs Exchange tokens reenabled, the administrator must contact Microsoft. |
| October 2025 | Exchange online tokens are turned off for all tenants and add-ins, including any that were reenabled. |
Outlook add-in migration FAQ
Why is Microsoft making Outlook add-ins migrate?
Switching to Microsoft Graph using Entra ID tokens is a big improvement in security for Outlook and Exchange customers. Entra ID (formerly Azure Active Directory) is a leader in the identity and access management space. Customers can take advantage of zero trust features such as conditional access, MFA requirements, continual token monitoring, real time safety heuristics, and more that aren't available with legacy Exchange tokens. Customers have much of their most important business data stored in Exchange, so it's vital that we ensure this data is protected. Migrating the whole Outlook ecosystem to using Entra ID tokens with Microsoft Graph greatly improves security for customer data.
Can my Outlook add-in get an exception to finish the migration later?
Unfortunately, no. We're following the timeline specified in the previous tables. We recognize that this migration is happening quickly, but we can't offer exceptions to any partners. Migrating away from legacy tokens by the established timeline is a commitment to customers and their security teams. This effort will greatly improve protection of customers' vital email data.
Does my Outlook add-in have to migrate to NAA?
No. Outlook add-ins don't have to use NAA, although NAA offers the best authentication experience for users and best security posture for organizations. If add-ins aren't using legacy Exchange tokens, they won't be affected by the deprecation of Exchange tokens. Add-ins using MSAL.js or other SSO methods that rely on Entra ID will continue to work.
How do I know if my Outlook add-in relies on legacy tokens?
To find out whether your add-in uses legacy Exchange user identity tokens and callback tokens, you can search your code for calls to the following APIs.
makeEwsRequestAsyncgetUserIdentityTokenAsyncgetCallbackTokenAsync
If your add-in calls any of these APIs, you should adopt NAA and migrate to using Entra ID tokens to access Microsoft Graph instead.
Which Outlook add-ins are in scope?
Many of our most important add-ins are in scope. If your add-in is using EWS or Outlook REST to access Exchange Online resources, it almost certainly needs to migrate off of legacy Outlook tokens to NAA. If your add-in is for Exchange on-premises only (for example, Exchange 2019), it is not affected by this announcement.
What will happen to my Outlook add-ins if I don't migrate to NAA?
If you don't migrate your Outlook add-ins to NAA, they'll stop working as expected in Exchange Online. When Exchange tokens are turned off (according to the previous tables), Exchange Online will block legacy token issuance. Any add-in that uses legacy tokens won't be able to access Exchange online resources. If your add-in only works on-premises or if your add-in is on a deprecation path, you may not need to update. However, most add-ins that access Exchange resources through EWS or Outlook REST will have to migrate to continue functioning as expected.
How do I migrate my Outlook add-ins to NAA?
To support NAA in your Outlook add-in, please refer to the following documentation and sample.
As an admin, how do I know which add-ins in my org need to be updated?
Add-ins use the legacy Exchange tokens to get resources from Exchange through the EWS or Outlook REST APIs. Sometimes, an add-in will require Exchange resources for some use cases and not others, making it especially difficult to figure out whether the add-in requires an update. As much as is practical, we recommend reaching out to add-in developers and owners to ask them if their add-in code references the following APIs:
makeEwsRequestAsyncgetUserIdentityTokenAsyncgetCallbackTokenAsync
As an admin, I don't own an add-in that needs an update. What should I do?
If you rely on an independent software vendor (ISV) for your add-in, we recommend reaching out as soon as possible to confirm they have a plan and a timeline for moving off of legacy Exchange tokens. ISV developers should reach out directly to their Microsoft contacts with questions to ensure they're ready for the end of Exchange legacy tokens. If you rely on a developer within your organization, we recommend asking them to reach out to the Outlook extensibility PM team on GitHub: https://github.com/officedev/office-js/issues.