New Nested App Authentication for Office Add-ins: Legacy Exchange tokens off by default in October 2024
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.
Light
Dark
10 comments
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 we have an update in that area if that’s helpful.
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.
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 you very much
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 the best step to take next.
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 future) having more strict ITP policies enabled?
Or is it a requirement to switch to the new NAA flow to support these browsers?
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 user’s client: https://learn.microsoft.com/en-us/office/dev/add-ins/develop/enable-nested-app-authentication-in-your-add-in. Or, you can set up a middle tier in your add-in backend that brokers access tokens for your add-in: https://learn.microsoft.com/en-us/office/dev/add-ins/develop/sso-in-office-add-ins
I need to check with our authentication team to give you advice on how NAA interacts with Safari ITP policies. In general, our guidance is that add-ins should use NAA because it has broader feature coverage, is simpler to integrate with your add-in, and also doesn’t require any server side infrastructure to broker tokens for the add-in running on the client. I will check and let you know if we have any additional guidance on how NAA works with ITP or whether we recommend SSO with a middle tier as a fallback in that scenario: https://learn.microsoft.com/en-us/office/dev/add-ins/develop/sso-in-office-add-ins
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 on the use of popups which are known to not be as reliable.
Is there any solution either in the OBO or NAA flow where we do not have to rely on popups in the case of Safari? And other browsers as well as soon as they implement similar ITP policies by default?
I am unsure how to have our backend broker access tokens as you mentioned. The requests from frontend to backend still need to be validated by the backend and after reading the document you referenced it seems this still relies on the same principle as the OBO flow, by using getAccessToken and having a fallback authentication method by utilizing the exchange identity token.
The first which does not work in Safari nor on iOS and the second which will be phased out in October.
I would be very interested to hear how the NAA interacts with Safari ITP policies.
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 flow: