Upcoming authentication change for Outlook add-ins on October 2024

We wanted to make everyone aware of the blog post that went live on the Microsoft Dev blog, talking about new Nested App Authentication for Office Add-ins requirement that is going to be mandatory for Outlook add-ins by October 2024.

While this post is quite dev-focused, we wanted to make sure people in the Outlook community working or creating Outlook add-ins see it.

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.

• makeEwsRequestAsync
• getUserIdentityTokenAsync
• getCallbackTokenAsync

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:

1. Register your add-in with Entra ID as an application.
2. Update your redirect URIs to support trusted brokers.
3. Update your MSAL.js configuration to allow native bridging.
4. Add a fall back authentication method.
5. 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.