Important: There was an update to the timeline for turning off Exchange online tokens. For the correct timeline, see Updates on deprecating legacy Exchange Online tokens for Outlook add-ins.
We’re excited to announce the public preview of Nested App Authentication (NAA). NAA provides simpler authentication and top tier identity protection through APIs designed specifically for add-ins in Office hosts.
We’re also announcing that legacy Exchange user identity tokens and callback tokens will be turned off by default for all Exchange Online tenants in October 2024. This is part of Microsoft’s Secure Future Initiative to give organizations the tools they need in the current threat landscape. Add-in developers who access Exchange data through EWS or Outlook REST must take immediate action to ensure their add-ins are ready before legacy Exchange tokens are off by default in October 2024. NAA is the best authentication option for affected add-ins; we recommend beginning work on proof of concepts using the NAA preview and adopting NAA soon after general availability.
The email threat landscape
Last year, Microsoft published data showing the increasing frequency and sophistication of attacks by brazen nation state actors. We also documented our approach to protecting customers from these attacks: Microsoft’s Secure Future Initiative.
A core pillar of this initiative is strengthening identity protection against highly sophisticated attacks. Email data is valuable and constantly pursued by bad actors; Microsoft and our add-in partners must strengthen add-in identity protection. Add-in developers know they should rely on proven authentication libraries, such as Microsoft’s MSAL.js, to handle the vagaries of authentication while developers focus on their apps’ unique value. However, relying on libraries in the Office add-in space was difficult: add-ins run within a host app, which makes it challenging to get user consent to access resources on a user’s behalf, accept authentication factors from users, and operate within the Office environment.
NAA simplifies Office add-in specific authentication with APIs that work for add-ins nested within Office hosts, making it simple to get consent, accept the latest and safest authentication factors, and allow customer admins to secure their environment with Entra ID policies.
Alongside our announcement of NAA, we’re preparing to deactivate legacy Exchange user identity tokens and callback tokens for all Exchange Online tenants in October 2024. Unlike the Entra ID tokens provided through NAA, these legacy tokens no longer provide sufficient support for organizations’ response to threats against email data.
Summary of timeline and changes
- April 2024
- NAA enters public preview. Any add-in using legacy Exchange user identity tokens and callback tokens must be migrated to NAA. Add-in developers should evaluate which of their add-ins use legacy Exchange tokens and begin planning and development to migrate all affected add-ins.
- October 2024
- Exchange Online blocks legacy Exchange user identity tokens and callback tokens in all tenants by default. Add-ins that haven’t adopted NAA and rely on legacy Exchange tokens will be unable to call EWS and Outlook REST unless admins opt into continued legacy token issuance.
- Exchange 2019 and other on-premises versions of Exchange won’t block legacy Exchange user identity tokens and callback tokens.
Adopt NAA in add-ins as soon as possible
Approaches for new add-ins
NAA is the best approach for any new add-in development. You may also use other approaches for authentication such as the on-behalf-of flow single sign-on (SSO) getAccessToken API in office.js, custom implementations of MSAL.js, or Entra ID SSO. Exchange legacy tokens and EWS or Outlook REST solutions aren’t permitted or supported.
To get access to Exchange resources, you should use Microsoft Graph. Graph is the best approach for access to Exchange Online resources—EWS is on the path to retirement. Exchange Online will stop issuing legacy Exchange user identity tokens and callback tokens in October 2024.
Approaches for existing add-ins
For existing add-ins, developers need to evaluate whether their add-ins use legacy Exchange user identity tokens and callback tokens as soon as possible. These tokens are used by add-ins to request resources from EWS and Outlook REST, which are on deprecation pathways. To evaluate whether your add-in uses legacy Exchange tokens, look for calls to the following APIs.
If your add-in uses legacy Exchange tokens and works with Exchange Online, you must adopt NAA as soon as possible. This is necessary to maintain compatibility with Exchange Online. Add-ins used only in on-premises environments don’t need to be updated.
We also recommend adopting NAA if you use Office SSO today. The Office SSO API isn’t deprecated, but NAA is easier to implement as a developer and provides a better user experience.
Technical steps to adopt NAA
To adopt NAA in each of your add-ins, you should follow these steps:
- Register your add-in with Entra ID as an application.
- Update your redirect URIs to support trusted brokers.
- Update your MSAL.js configuration to allow native bridging.
- Add a fall back authentication method.
- Test your add-in.
The steps to support NAA are covered here: Enable SSO in an Office Add-in using nested app authentication (preview).
Simpler and safer authentication for Outlook add-ins
The launch of NAA provides Outlook add-in developers with a simpler and safer way to do add-in authentication. At the same time, the end of support for legacy Exchange tokens helps organizations secure their identity and access management estate. The work that each add-in developer does to migrate away from legacy Exchange tokens and EWS/Outlook REST helps organizations across the world keep the vital data in their Exchange environments safe.
We recognize that the October 2024 end of support for legacy Exchange tokens will come quickly. We recommend developers immediately start to identify add-ins that use legacy tokens using the steps described in this blog post and in our documentation. If your add-in consumes legacy tokens, you should make plans to migrate to Entra ID tokens and Microsoft Graph before October 2024. Your investment in this migration will pay dividends for organizations that can better manage identity and access in add-ins moving forward.
We’re currently using Exchange tokens and Outlook REST API in our event-based add-in within the OnMessageSend event. Will NAA support event-based add-ins?
Hi Ben,
Will NAA work in IE11 webviews/browsers? Some office volume licenses seem to be using IE11 webviews (https://learn.microsoft.com/en-us/office/dev/add-ins/concepts/browsers-used-by-office-web-add-ins).
Will this affect the Outlook actions in Power Automate? I started having issues with the Get mail tips for mailbox (V2) action when this message was posted on April 9. The error message flow he low was that the access token was no longer valid. To resolve the issue, I had to recreate the flow. But it has failed again two weeks later with the same issue. The error message I am getting from the...
We are currently developing an outlook add-in that will be targeting multiple customers across different platforms.
We are trying to setup the authentication layer to support the Safari browser according to the fallback authentication method listed in Microsoft docs by using the Exchange identity token.
Judging from this blog post, this identity token seems to no longer be possible to retrieve after October.
Is there another approach to support Safari (and other browsers in the...
You are correct that the Exchange identity token will be turned off by default after October, so it will no longer be a good option for this use case.
Microsoft has general guidance on dealing with ITP in Safari here: https://learn.microsoft.com/en-us/entra/identity-platform/reference-third-party-cookies-spas
For add-ins specifically, you can use NAA to enable the implicit flow, which treats the add-in like a Single Page App because it cannot maintain a secret given that all its logic executes on the...
We have coded all our graph communication flow into our backend code as was recommended in the docs (https://learn.microsoft.com/da-dk/office/dev/add-ins/develop/overview-authn-authz) when using the recommended on-behalf-of flow, so it will be a big change for us to change our code to call Graph from the frontend code instead.
The solution mentioned in your first link suggests the PKCE flow. But since redirects are not an option as the add-in resides in an iframe, this solution relies solely...
Hi Ben Siler,
I lost my phone which had Microsoft Authenticator installed for logging into the admin account of the E5. When I try to log in, I'm being asked to verify using Microsoft Authenticator but I can't. I also haven't backed up the data of Microsoft Authenticator so I can't restore it. Is there any way for me to log in again?
I'm sorry for the off-topic question, but I really need help.
Thank...
I'm hoping you have another admin account that can be used to access your tenant, but from your question I'm guessing that you don't have any other account that could provide admin access. Our recommended best practices (which may be too late in this case) for making sure you don't lose access are documented here: https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/security-emergency-access
If there are no accounts at your org that you can use to regain access, contacting Microsoft support is probably...
Does this change will have effect on EWS REST API Calls as well?
Yes, this change will affect all EWS API calls that rely on legacy Exchange tokens. For clarification, are you asking about calls from an add-in/app backend directly to EWS (that is, not using Office JS APIs)? Those calls will be affected as well since the legacy Exchange user identity tokens and callback tokens will be turned off by default for any calls to Exchange Online in Oct 2024.
Are there any more details about what “turned off” means for these tokens? Will calls to the listed APIs return empty or throw? Or will they still return a token that doesn’t work?
Is it possible to turn these tokens off today in a dev tenant to test that all authentication paths work and/or fail as expected?
"Turned off" means that the affected tokens (Exchange user identity tokens and callback tokens) will no longer be issued when an app or add-in hits these endpoints: makeEwsRequestAsync, getUserIdentityTokenAsync, and getCallbackTokenAsync. The endpoint will return a 4xx error. It won't return a non-functional token.
It is not possible yet to turn these tokens off for testing, but please keep your eyes out for improvements in that area soon. I can leave another reply here when...