Skip to content

[NAA] Update FAQ for new error message #5256

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

[NAA] Update FAQ for new error message #5256

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d448089
Update for new error message
davidchesnut Jun 25, 2025
0a61c3e
fix broken link
davidchesnut Jun 25, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 6 additions & 9 deletions docs/outlook/faq-nested-app-auth-outlook-legacy-tokens.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ description: Nested app authentication and Outlook legacy tokens deprecation FAQ
ms.service: microsoft-365
ms.subservice: add-ins
ms.topic: faq
ms.date: 06/18/2025
ms.date: 06/25/2025
---

# Nested app authentication and Outlook legacy tokens deprecation FAQ
Expand Down Expand Up @@ -242,10 +242,9 @@ If legacy Exchange Online tokens are off, you'll see an error displayed in the c

![Screen shot of an error in the console window.](../images/script-lab-error-exchange-token.png)

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

- `GenericTokenError: An internal error has occurred.`
- `InternalServerError: The Exchange server returned an error. Please look at the diagnostics object for more information.`
- `Legacy Exchange token retrieval is no longer supported. Contact your administrator for assistance. Error ID = '5EF6BA0D-32C5-4772-9F37-638AC7C56b68'.`

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?](#can-i-turn-exchange-online-legacy-tokens-back-on).

Expand Down Expand Up @@ -278,8 +277,7 @@ If your add-in is for Exchange on-premises only (for example, Exchange 2019), it

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."
- `Legacy Exchange token retrieval is no longer supported. Contact your administrator for assistance. Error ID = '5EF6BA0D-32C5-4772-9F37-638AC7C56b68'.`

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.

Expand Down Expand Up @@ -347,10 +345,9 @@ Once you've updated your add-in to use NAA, you should test it on all platforms

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](turn-exchange-tokens-on-off.md).

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](/javascript/api/office/office.asyncresult). If either of the following errors is returned, switch to NAA.
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](/javascript/api/office/office.asyncresult). If the following error 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.`
- `Legacy Exchange token retrieval is no longer supported. Contact your administrator for assistance. Error ID = '5EF6BA0D-32C5-4772-9F37-638AC7C56b68'.`

#### Test fallback code for Trident+ webview

Expand Down
7 changes: 5 additions & 2 deletions docs/outlook/turn-exchange-tokens-on-off.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,15 @@ description: Turn legacy Exchange Online tokens on or off
ms.service: microsoft-365
ms.subservice: add-ins
ms.topic: how-to
ms.date: 05/22/2025
ms.date: 06/25/2025
---

# Turn legacy Exchange Online tokens on or off

Legacy Exchange Online tokens are deprecated and will be turned off across Microsoft 365 tenants starting February 17th, 2025. If you're a developer migrating your Outlook add-in from legacy tokens to Entra ID tokens and nested app authentication, you'll need to test updates to your add-in. Use the Exchange Online PowerShell cmdlets to turn off legacy tokens in a test tenant to confirm that your updated Outlook add-in is working correctly.
Legacy Exchange Online tokens are deprecated and are being turned off across Microsoft 365 tenants. If you're a developer migrating your Outlook add-in from legacy tokens to Entra ID tokens and nested app authentication, you'll need to test updates to your add-in. Use the Exchange Online PowerShell cmdlets to turn off legacy tokens in a test tenant to confirm that your updated Outlook add-in is working correctly.

> [!IMPORTANT]
> Beginning in June 2025 the commands in this article will be disabled as part of turning off legacy Exchange Online tokens. For more information see [Can I turn Exchange Online legacy tokens back on?](faq-nested-app-auth-outlook-legacy-tokens.md#can-i-turn-exchange-online-legacy-tokens-back-on) in the [Nested app authentication and Outlook legacy tokens deprecation FAQ](https://aka.ms/NAAFAQ).

For more information about deprecation of legacy Exchange Online tokens, see [Nested app authentication and Outlook legacy tokens deprecation FAQ](https://aka.ms/NAAFAQ).

Expand Down