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.
For more information about deprecation of legacy Exchange Online tokens, see Nested app authentication and Outlook legacy tokens deprecation FAQ.
Connect to Exchange Online PowerShell
To run the commands you need to connect to Exchange Online PowerShell.
- Open PowerShell.
- Run the command
Import-Module -Name ExchangeOnlineManagement
. For more information about this command, see Exchange Online PowerShell. - To be sure you are on the latest version of the module, run the command
Update-Module -Name ExchangeOnlineManagement
. - Run the command
Connect-ExchangeOnline
. Sign in with your Microsoft 365 administrator credentials.
Turn off legacy Exchange Online tokens
The Set-AuthenticationPolicy
command controls the issuance of legacy Exchange Online tokens. When issuance is turned off, add-ins can no longer request user identity tokens or callback tokens. Existing tokens already issued will continue to work until they expire. It can take up to 24 hours before all request from Outlook add-ins for legacy Exchange Online tokens are blocked.
To turn legacy tokens off, run the following command.
Set-AuthenticationPolicy –BlockLegacyExchangeTokens -Identity "LegacyExchangeTokens"
The command turns off legacy tokens for the entire tenant. If an Outlook add-in requests a legacy token, it won’t be issued a token.
Note
If you've confirmed that your tenant is not using any add-ins that require legacy Exchange Online tokens, we recommend you turn off legacy Exchange Online tokens as a security best practice. For more information on how to determine if you tenant has add-ins using legacy tokens, see the Nested app authentication and Outlook legacy tokens deprecation FAQ.
Turn on legacy Exchange Online tokens
To turn legacy tokens on, run the following command. It can take up to 24 hours before all requests from Outlook add-ins for legacy tokens are allowed.
Set-AuthenticationPolicy –AllowLegacyExchangeTokens -Identity "LegacyExchangeTokens"
Important notes about this command.
- Legacy Exchange tokens issued to Outlook add-ins before token blocking was implemented in your organization will remain valid until they expire.
- If you turn on legacy Exchange Online tokens, then they won't be turned off in February 2025 when Microsoft turns them off for all tenants. For more information, see Nested app authentication and Outlook legacy tokens deprecation FAQ.
- You’ll only be able to turn tokens back on until June 2025 when all legacy tokens in all tenants will be forced off. For more information, see the Nested app authentication and Outlook legacy tokens deprecation FAQ.
- Although the
-Identity
parameter is required, it doesn't affect any specific authentication policy. The command always applies to the entire organization regardless of what value you use. We show the value asLegacyExchangeTokens
in the examples to keep the intent clear.
Get the status of legacy Exchange Online tokens and add-ins that use them
To view the status of legacy Exchange Online tokens, run the following command.
Get-AuthenticationPolicy -AllowLegacyExchangeTokens
The command returns whether AllowLegacyExchangeTokens
is true or false, such as the following example in PowerShell.
PS C:\> Get-AuthenticationPolicy -AllowLegacyExchangeTokens
AllowLegacyExchangeTokens: False
Allowed: []
Blocked: []
PS C:\>
We are deploying an update that enables a report of which add-ins requested an Exchange token in the last seven days, and whether the request was allowed or blocked. If your tenant has this update, you'll see a list of requests displayed in the Allowed or Blocked list. If an add-in was granted the token request, it appears in the Allowed list along with the date of the request. If the token request was denied, it appears in the Blocked list. It's possible for the same add-in to appear in both lists. This happens if the add-in was allowed to get tokens, but then tokens were turned off. The following example shows an add-in was blocked when it requested a token on February 25th.
PS C:\> Get-AuthenticationPolicy -AllowLegacyExchangeTokens
AllowLegacyExchangeTokens: False
Allowed: []
Blocked:
[
{ "49d3b812-abda-45b9-b478-9bc464ce5b9c" : "2025-02-25" }
]
PS C:\>
To identify any add-ins that were allowed or blocked Exchange tokens, use the Get-App
command as shown in the following example.
PS C:\> Get-App -Identity 49d3b812-abda-45b9-b478-9bc464ce5b9c | Select-Object -Property DisplayName, AppVersion, MarketplaceAssetID, ProviderName
DisplayName AppVersion MarketplaceAssetID ProviderName
----------- ---------- ------------------ ------------
Script Lab for Outlook 4.0.0.0 WA200001603 Microsoft
The previous Script Lab example uses the Get a user identity token sample and the getUserIdentityTokenAsync
function to make the request.
Note
The Get-AuthenticationPolicy -AllowLegacyExchangeTokens
command is the only way to view legacy token status. Other commands, such as Get-AuthenticationPolicy | Format-Table -Auto Name
, don't return the legacy token status.
The Get-AuthenticationPolicy
command only shows the legacy token status as set by the administrator. If the administrator has never changed the settings, the command returns (Not Set)
. If the token status is (Not Set)
when the February deployment by Microsoft to turn off legacy tokens is implemented, the token status will still be (Not Set)
even though legacy tokens are off. The following table shows the behavior of legacy Exchange Online tokens based on the token status when the change is applied.
Legacy token admin setting | Legacy token behavior before February change | Legacy token behavior after February change | Legacy token behavior after June change |
---|---|---|---|
(Not Set) | Tokens on | Tokens off | Tokens off |
False | Tokens off | Tokens off | Tokens off |
True | Tokens on | Tokens on | Tokens off |