Nested app authentication and Outlook legacy tokens deprecation FAQ

Exchange user identity tokens and callback tokens are deprecated and will be completely turned off by June 2025. 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 Exchange online tokens?

Legacy Exchange online tokens have already been turned off for most tenants. We've provided tooling for administrators to reenable Exchange tokens for tenants and add-ins if those add-ins aren't yet migrated to NAA. For more information, see Can I turn legacy tokens back on?.

When is NAA generally available for my channel?

The general availability (GA) date for NAA depends on which channel you are using.

How do I handle legacy tokens turned off in Semi-Annual Extended Channel, which doesn't support NAA yet?

Semi-Annual Extended Channel won't support NAA until June 2025. This means even if add-ins are updated to support NAA, and no longer use legacy Exchange Online tokens, they won't function on this channel. If you are using Semi-Annual Extended Channel as an administrator, we recommend the following.

• Check if your tenant is using any add-ins that require legacy Exchange Online tokens. For more information, see Find Outlook add-ins that use legacy Exchange Online tokens.
• If you have deployed add-ins that require legacy Exchange Online tokens, and the add-ins are necessary for your organization, we recommend you turn on tokens now so that they continue to function. To turn tokens on, see Turn legacy Exchange Online tokens on or off.

Are COM Add-ins affected by the deprecation of legacy Exchange Online tokens?

It's very unlikely any COM add-ins are affected by the deprecation of legacy Exchange Online tokens. Outlook web add-ins are primarily affected because they can use Office.js APIs that rely on Exchange tokens. For more information, see How do i know if my outlook add in relies on legacy tokens. The Exchange tokens are used to access Exchange Web Services (EWS) or Outlook REST APIs, both of which are also deprecated. If you suspect a COM add-in might be affected, you can test it by using it on a tenant with Exchange tokens turned off. For more information, see Turn legacy Exchange Online tokens on or off.

Microsoft 365 administrator questions

How do I perform a scream test?

Legacy Exchange Online tokens will be turned off across all tenants in June 2025. We recommend that administrators perform a scream test as soon as possible to determine if there are any add-ins that could be broken by this change. This will give you time to reach out to publishers of any affected add-ins to address breaking issues before the June deadline.

Before performing the scream test you may want to let your users know in advance, such as through email, that there will be a test to turn off legacy tokens and that it may affect some Outlook add-ins. You should consider providing users the following information.

• The expected time period of the test.
• If there are known Outlook add-ins that will break, such as add-ins deployed from Microsoft AppSource that you’ve already identified.
• That in general, Outlook add-ins shouldn’t break. However, if they do see issues, ask users to report the name, and description of the add-in, along with any error information observed.

Use the following steps to perform the test.

1. Run the following command to turn off legacy Exchange Online tokens on your tenant. For details on how to use this command, see Turn legacy Exchange Online tokens on or off.

   Set-AuthenticationPolicy -BlockLegacyExchangeTokens -Identity "LegacyExchangeTokens"

2. Wait a suitable amount of time for users to report any issues with add-ins. It takes approximately 24 hours for the command to turn off legacy Exchange Online tokens for all users. It may take another day or two for users to report any issues with Outlook add-ins.

3. Identify any affected Outlook add-ins. If users submit issues identifying breaking issues, be sure to get the name and description of the Outlook add-in affected. Also capture the error, or behavior so this information can be passed along to the publisher.

4. If any business-critical add-ins are broken, turn tokens back on using the following command. For details on how to use this command, see Turn legacy Exchange Online tokens on or off.

   Set-AuthenticationPolicy -AllowLegacyExchangeTokens -Identity "LegacyExchangeTokens"

   It takes approximately 24 hours for tokens to turn back on for all users on the tenant.

5. If there are no reports of breaking issues, we recommend you leave legacy Exchange Online tokens off as a security best practice.

How to contact publishers

For any Outlook add-ins that break or have issues when tokens are off, you’ll need to reach out to the publishers to learn more about their plans to update. In some cases, the add-in may be developed by your own organization. You’ll need to reach out to the appropriate development team in your organization.

Commands to identify the publisher

There are some Exchange Online PowerShell commands you can use to track down additional information about Outlook add-ins.

To find a list of add-ins installed on a user’s computer, the user can run the following command.

Get-App | Select-Object -Property ProviderName, DisplayName, AppId

The following screenshot shows an example of running the Get-App command.

The ProviderName will help you identify who published the add-in so that you can contact them. The AppId can be used to get additional details about the add-in.

To find information about an add-in by AppId use the following command.

Get-App -Identity {identity} | Select-Object -Property ProviderName, DisplayName

The following screenshot shows an example of using the ID of Bing Maps to get more information.

You may also find additional information in the add-in's manifest file. The manifest contains URL endpoints which can also help you identify and contact the publisher. Use the following command to get the manifest.

Get-App -Identity {identity} | Select-Object -Property ManifestXml

The following screenshot shows an example of using the ID to get the XML manifest for Bing Maps.

Can I turn Exchange Online legacy tokens back on?

Yes, there are PowerShell commands you can use to turn legacy tokens on or off in any tenant. For more information on how to turn legacy tokens on or off, see Turn legacy Exchange Online tokens on or off.

In June 2025, legacy tokens will be turned off and you won't be able to turn them back on without a specific exception granted by Microsoft. In October 2025, it won't be possible to turn on legacy tokens and they'll be disabled for all tenants. We'll update this FAQ with additional information once the exception process is ready.

How does the admin consent flow work?

Independent software vendors (ISVs) are updating their add-ins to use Entra ID tokens and Microsoft Graph scopes. When the add-in requests an access token, it must have admin or user consent. If the administrator consents, all users on the tenant can use the add-in for the scopes the add-in requires. Otherwise, each end-user will be prompted for consent, if user consent is enabled. For a better experience because the users aren't prompted, complete admin consent.

One option for consent is that the ISV provides you with an admin consent URI.

1. The add-in developer provides an admin consent URI. If this is not in the documentation they provide, you need to contact them for more information.
2. The administrator browses to the admin consent URI.
3. The administrator is prompted to sign in and consent to a list of scopes that the add-in requires.
4. Once complete, the browser redirects to a web page from the ISV, which should show the consent was successful.

As an alternative, the ISV may provide an updated app manifest that will prompt for admin consent as part of central deployment. In this scenario, when you deploy the updated app manifest, you'll be prompted to consent before the deployment can complete. There is no need for an admin consent URI.

Finally, if the add-in is published in the Microsoft 365 store, the update will deploy automatically and the administrator will be prompted to consent to the scopes. If the administrator doesn't consent, users won't be able to use the updated add-in.

What if the add-in doesn't work after admin consent?

Ensure you don't disable features, or revoke permissions that the add-in requires. For an example, see modifying mailbox policy properties. The add-in uses delegated permissions and therefore has access to the same resources as the signed-in user. However, if a policy or setting blocks the user from a particular resource or action, the add-in will also be blocked.

How do I deploy add-in updates from an ISV?

If you have an add-in that uses legacy Exchange tokens, you should reach out to your ISV for information about their timeline to migrate their add-in to use NAA. Once the ISV migrates their add-in, they will most likely provide an admin consent URL. For more information, see How does the admin consent flow work? .

The ISV may also provide you with an updated app manifest to deploy through centralized deployment. During centralized deployment, this may prompt you to consent to any Microsoft Graph scopes the add-in requires. In this scenario you won't need to use an admin consent URI.

If the add-in is deployed from Microsoft AppSource, most likely you'll be prompted to consent to Microsoft Graph scopes when the ISV rolls out updates to the add-in. Until you consent, users on the tenant won't be able to use the new version of the add-in with NAA.

Which add-ins in my organization are impacted?

We published a list of all Outlook add-ins published to the Microsoft store that use legacy tokens as of October 2024. For more information on how to use the list and build a report of Outlook add-ins that are potentially using legacy tokens, see Find Outlook add-ins that use legacy Exchange Online tokens.

Add-ins may use the legacy tokens to get resources from Exchange through the EWS or Outlook REST APIs. Sometimes an add-in requires Exchange resources for some use cases and not others, making it difficult to figure out whether the add-in requires an update. We recommend reaching out to add-in developers and owners to ask them if their add-in code references the following APIs.

• makeEwsRequestAsync
• getUserIdentityTokenAsync
• getCallbackTokenAsync

If you rely on an ISV for your add-in, we recommend you contact them 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, they should review this FAQ and the article Enable SSO in an Office Add-in using nested app authentication. Any questions should be raised on the OfficeDev/office-js GitHub issues site.

Where do I find which add-ins have consent?

Once the admin or a user consents, it will be listed in the Microsoft Entra admin center. You can find app registrations using the following steps.

1. Go to https://entra.microsoft.com/#home and sign in as admin on your tenant.
2. In the left navigation pane, select Applications > Enterprise applications.
3. On the Enterprise applications page, in the Manage section, select All applications.
4. Select the Add-in. This will open an overview page. In the overview page, select Permissions. There are two views for permissions; Admin consent, and User consent. Select User consent to see any individual consents.

Is there a list of publishers that have updated their add-ins?

Some widely used Outlook add-in publishers have already updated their add-ins as listed below.

• Appfluence Priority Matrix for Outlook
• Atlassian Jira Cloud for Outlook
• Box for Outlook
• Clickup for Outlook
• iEnterprises® - Outlook Connector
• HubStar Connect
• SalesForce for Outlook
• LawToolBox
• OnePlace Solutions
• Set-OutlookSignatures Benefactor Circle
• Wrike
• Zoho CRM for Email
• Zoho Recruit for Email
• Zoho Projects for Email
• Zoho Sign for Outlook
• Zoho WorkDrive for Email
• Invoice and Time Tracking - Zoho Invoice

If the publisher updated their manifest, and the add-in is deployed through the Microsoft store, you'll be prompted as an administrator to upgrade and deploy the updates. If the publisher updated their manifest, and the add-in is deployed through central deployment, you'll need to deploy the new manifest as an administrator. In some cases the publisher may have an admin consent URI you need to use to consent to new scopes for the add-in. Reach out to publishers if you need more information about updating an add-in.

Some add-ins are breaking. Can I tell if this is because Exchange tokens were turned off?

If you notice that an add-in has issues and suspect it may be affected by Exchange tokens turned off, please take the following actions.

Check the list of known add-ins

We posted a list of add-ins that were known to be using legacy Exchange tokens as of October 2024. If an add-in is on this list, you should reach out to the publisher to see if there are updates available. For more information, see Find Outlook add-ins that use legacy Exchange Online tokens

Check if tokens are off by using Script Lab

Check if legacy Exchange Online tokens are off for a user by using the Script Lab add-in.

1. Install Script Lab for Outlook.

2. Sign in to Outlook with the user account/mailbox that is affected. Exchange tokens can be off for one user, but not another until the rollout is complete.

3. From an existing or new email, open Script Lab from the Apps menu, and choose Code from the Script Lab menu.

   

4. In the Script Lab task pane, select the backstage icon (it has three lines).

   

5. Select Samples and then search for the Get a user identity token sample. Select this sample to open it in the code editor.

   

6. After the code for the sample is loaded, select Run > Run in this pane.

   

7. After the code runs, select Get token.

If legacy Exchange Online tokens are on, you'll see a token displayed in the console as a Base64-encoded string.

If legacy Exchange Online tokens are off, you'll see an error displayed in the console as shown below.

The actual error and code can vary, but often you will see error code 9017 or 9018 along with the following error descriptions.

• GenericTokenError: An internal error has occurred.
• InternalServerError: The Exchange server returned an error. Please look at the diagnostics object for more information.

If an add-in is affected by Exchange tokens turned off, you can turn them back on. For more information, see Can I turn Exchange Online legacy tokens back on?.

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 leading cloud-based identity and access management service. 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 store important business data stored in Exchange, so it's vital that we ensure this data is protected. Migrating the whole Outlook ecosystem to use Entra ID tokens with Microsoft Graph greatly improves security for customer 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 the 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, search your code for calls to the following APIs.

• makeEwsRequestAsync
• getUserIdentityTokenAsync
• getCallbackTokenAsync

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 major 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's not affected by this change.

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, Exchange Online will block legacy token issuance. Any add-in that uses legacy tokens won't be able to access Exchange online resources. When your add-in calls an API that requests an Exchange token, such as getUserIdentityTokenAsync, it gets a generic error similar to the following with error codes such as 9017 or 9018.

• "GenericTokenError: An internal error has occurred."
• "InternalServerError: The Exchange server returned an error. Please look at the diagnostics object for more information."

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 must 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.

• Enable SSO in an Office Add-in using nested app authentication.
• Outlook add-in with SSO using nested app authentication.

How do I keep up with the latest guidance?

We'll update this FAQ as any new information becomes available. We'll share additional guidance moving forward on the Office Add-ins community call and the M365 developer blog. Finally, you can ask questions about NAA and legacy Exchange Online token deprecation on the OfficeDev/office-js GitHub issues site. Please put "NAA" in the title so we can group and prioritize issues.

If you submit an issue, please include the following information.

• Outlook client version.
• Outlook release channel audience (for client).
• Screen capture of the issue.
• The platform where the issue occurs (Windows, Outlook (new), Mac, iOS, Android).
• Session id where the issue is encountered.
• Type of account being used.
• Version of msal-browser.
• Logs from msal-browser.

Developer questions

How do I get more debug information from MSAL and NAA?

Use the following code to enable debug information in the msalConfig when you initialize the nestable public client application. This will log additional details to the console.

const msalConfig = {
  auth: {...},
  system: {
    loggerOptions: {
      logLevel: LogLevel.Verbose,
      loggerCallback: (level, message, containsPii) => {
        switch (level) {
          case LogLevel.Error:
            console.error(message);
            return;
          case LogLevel.Info:
            console.info(message);
            return;
          case LogLevel.Verbose:
            console.debug(message);
            return;
          case LogLevel.Warning:
            console.warn(message);
            return;
        }
      },
    }
  }
};

Test your updated add-in

Once you've updated your add-in to use NAA, you should test it on all platforms you support, such as Mac, mobile, web, and Outlook on Windows.

Test when Exchange tokens turned off

To test that your add-in works correctly when Exchange tokens are turned off, deploy your add-in to a tenant with tokens turned off and test it. To turn tokens off, see Turn legacy Exchange Online tokens on or off.

If you've implemented a pattern where your code uses Exchange tokens but then falls over if they are unavailable, be sure you are checking for the correct errors. When a call to get an Exchange token fails, check the asyncResult.diagnostics. If either of the following errors is returned, switch to NAA.

• GenericTokenError: An internal error has occurred.
• InternalServerError: The Exchange server returned an error. Please look at the diagnostics object for more information.

Test fallback code for Trident+ webview

If your Outlook add-in supports Outlook 2016 or Outlook 2019 on Windows, test that it works correctly when the Trident+ (Internet Explorer 11) webview is used. When the Trident+ webview is used, your code must fall back to MSAL v2 to open a dialog and sign in the user. For more information on how to implement the fallback pattern, see Outlook add-in with SSO using nested app authentication including Internet Explorer fallback.

Testing in Trident+ and WebView2

Outlook 2016 and Outlook 2019 on Windows use the Trident+ or WebView2 based on various OS conditions.

• For more information on when Trident+ or Webview2 is used, see Browsers and webview controls used by Office Add-ins.
• For more information on how to determine which webview is running, see Support older Microsoft webviews and Office versions

What tokens does MSAL return and are there minimum scopes to request?

When you request a token through MSAL, it always returns three tokens.

MSAL always returns these three tokens. It requests the profile, openid, and offline_access as default scopes even if your token request doesn't include them. This ensures the ID and refresh tokens are requested. However, you must include at least one resource scope, such as user.read so that you get an access token. If not, the request can fail.

Should I validate the ID token from MSAL?

No. This is a legacy authentication pattern that was used with Exchange tokens to authorize access to your own resources. Passing the ID token over a network call to enable or authorize access to a service is a security anti-pattern. The ID token is intended only for the client (task pane) and there is no way for the service to reliably use the token to be sure the user has authorized access. For more information about ID token claims, see ID token claims reference.

It's very important that you always request an access token to your own services. The access token also includes the same ID claims, so you don't need to pass the ID token. Instead create a custom scope for your service. For more information about app registration settings for your own services, see Protected web API: App registration. When your service receives the access token, it can validate it, and use ID claims from inside the access token.

Why is the ID token not refreshed?

There is a known issue where MSAL sometimes doesn't refresh the ID token after it expires. This shouldn't cause any issues in your add-in since the ID token is only intended for use in your task pane to get basic user identity information, such as name and email. There's no reason to validate the ID token or check the expiration claim. If you need to authenticate the user to your own resources, use the access token which also contains user identity information. The ID token must never be passed outside of your client code that received it.

How do I determine if the user is an online or on-premise account?

You can determine if the signed-in user has an Exchange Online account or on-premise Exchange account by using the Office.UserProfile.accountType property. If the account type property value is enterprise, then the mailbox is on an on-premises Exchange server. Note that volume-licensed perpetual Outlook 2016 doesn’t support the accountType property. To work around this, call the ResolveNames operation in Exchange Web Service (EWS) in the Exchange on-premise server to get the recipient types.

How do I deploy my add-in to Microsoft AppSource

If you're publishing a new add-in to Microsoft AppSource, it will need to go through a certification process. For more information, see Publish your Office Add-in to Microsoft AppSource. If you're updating the manifest of an add-in that is already published to Microsoft AppSource, you need to go through the certification process again. You can update the add-in's source code on your web server any time without a need to go through the certification process.

If you're add-in uses SSO through NAA, your add-in must be in compliance with the following publishing guidelines.

• 1000.3 Authentication options
• 1120.3 Functionality

Be sure to handle admin consent properly. See Publish an add-in that requires admin consent for Microsoft Graph scopes

For additional deployment details, see Make your solutions available in Microsoft AppSource and within Office. If you update your add-in (change the manifest) you need to go through the certification process again. You can update your web server code any time without a need for review.

Related content

• Enable SSO in an Office Add-in using nested app authentication.
• Outlook add-in with SSO using nested app authentication.