Exchange user identity tokens and callback tokens will be turned off by default by 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?
After October 2024, Outlook add-ins that rely on legacy Exchange tokens will not work as expected since Exchange will no longer issue those legacy tokens by default.
April 2024
- NAA will be available in public preview. If your add-in uses legacy Exchange user identity tokens or callback tokens you should adopt NAA in your add-in. Developers can identify this token use by looking for calls to
makeEwsRequestAsync,getUserIdentityTokenAsync, orgetCallbackTokenAsyncin the add-in's code.
October 2024
- Exchange Online will block legacy Exchange user identity tokens and callback tokens by default in all tenants. Add-ins that have not adopted NAA and rely on legacy Exchange tokens won't function as expected.
- Exchange 2019 and other on-premises versions of Exchange will continue to allow legacy Exchange user identity tokens and callback tokens.
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 are not 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 after Oct 2024?
Unfortunately, no. We recognize that this migration is happening quickly, but we cannot offer exceptions to any partners. Migrating away from legacy tokens by October 2024 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 are not using legacy Exchange tokens, they won't be affected by their deprecation. Add-ins using MSAL.js or other SSO methods that rely on Entra ID will still work after October 2024.
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 will stop working as expected in Exchange Online. In October 2024, Exchange Online will block legacy token issuance by default in all tenants. Any add-in that uses legacy tokens will not 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 are ready for the end of Exchange legacy tokens on October 2024. 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.