Merge pull request #12360 from samantharamon/samramon-legacy-exchange-parameters

Update parameters for legacy Exchange tokens

Author: chrisda

exchange/exchange-ps/exchange/Get-AuthenticationPolicy.md

@@ -21,6 +21,7 @@ For information about the parameter sets in the Syntax section below, see [Excha
 
 ```
 Get-AuthenticationPolicy [[-Identity] <AuthPolicyIdParameter>]
+ [-AllowLegacyExchangeTokens]
  [-TenantId <String>]
  [<CommonParameters>]
 ```
@@ -44,6 +45,13 @@ Get-AuthenticationPolicy -Identity "Engineering Group"
 
 This example returns detailed information for the authentication policy named Engineering Group.
 
+### Example 3
+```powershell
+Get-AuthenticationPolicy -AllowLegacyExchangeTokens
+```
+
+In Exchange Online, this example specifies whether legacy Exchange tokens for Outlook add-ins are allowed in the organization.
+
 ## PARAMETERS
 
 ### -Identity
@@ -66,6 +74,31 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -AllowLegacyExchangeTokens
+This parameter is available only in the cloud-based service.
+
+The AllowLegacyExchangeTokens switch specifies whether legacy Exchange tokens are allowed for Outlook add-ins in your organization. You don't need to specify a value with this switch.
+
+Legacy Exchange tokens include Exchange user identity and callback tokens.
+
+**Important**:
+
+- Currently, the AllowLegacyExchangeTokens switch only specifies whether legacy Exchange tokens are allowed in your organization. For now, disregard the empty Allowed and Blocked arrays returned by the switch.
+- Legacy Exchange tokens will eventually be blocked by default in all cloud-based organizations. For more information, see [Nested app authentication and Outlook legacy tokens deprecation FAQ](https://learn.microsoft.com/office/dev/add-ins/outlook/faq-nested-app-auth-outlook-legacy-tokens#what-is-the-timeline-for-shutting-down-legacy-exchange-online-tokens).
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+Aliases:
+Applicable: Exchange Online, Exchange Online Protection
+
+Required: False
+Position: Named
+Default value: True
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### -TenantId
 This parameter is available only in the cloud-based service.
 

exchange/exchange-ps/exchange/Remove-AuthenticationPolicy.md

@@ -41,6 +41,13 @@ Remove-AuthenticationPolicy -Identity "Engineering Group"
 
 This example removes the authentication policy named "Engineering Group".
 
+### Example 2
+```powershell
+Remove-AuthenticationPolicy -Identity "LegacyExchangeTokens" -AllowLegacyExchangeTokens
+```
+
+In Exchange Online, this example enables legacy Exchange tokens to be issued to Outlook add-ins. This switch applies to the entire organization. The Identity parameter is required, and its value must be set to "LegacyExchangeTokens". Specific authentication polices can't be applied.
+
 ## PARAMETERS
 
 ### -Identity
@@ -66,7 +73,18 @@ Accept wildcard characters: False
 ### -AllowLegacyExchangeTokens
 This parameter is available only in the cloud-based service.
 
-This parameter is reserved for internal Microsoft use.
+The AllowLegacyExchangeTokens switch enables legacy Exchange tokens to be issued to Outlook add-ins for your organization. You don't need to specify a value with this switch.
+
+Legacy Exchange tokens include Exchange user identity and callback tokens.
+
+This switch applies to the entire organization. The Identity parameter is required, and its value must be set to "LegacyExchangeTokens". Specific authentication polices can't be applied.
+
+**Important**:
+
+- Apart from the Identity parameter, this switch disregards other authentication policy parameters used in the same command. We recommend running separate commands for other authentication policy changes.
+- It might take up to 24 hours for the change to take effect across your entire organization.
+- Legacy Exchange tokens issued to Outlook add-ins before token blocking was implemented in your organization will remain valid until they expire.
+- Legacy Exchange tokens will eventually be blocked by default in all cloud-based organizations. For more information, see [Nested app authentication and Outlook legacy tokens deprecation FAQ](https://learn.microsoft.com/office/dev/add-ins/outlook/faq-nested-app-auth-outlook-legacy-tokens#what-is-the-timeline-for-shutting-down-legacy-exchange-online-tokens).
 
 ```yaml
 Type: SwitchParameter

exchange/exchange-ps/exchange/Set-AuthenticationPolicy.md

@@ -77,6 +77,13 @@ Set-AuthenticationPolicy -Identity "Research and Development Group" -BlockLegacy
 
 In Exchange 2019, this example re-enables Basic authentication for Exchange Reporting Web Services in the authentication policy named Research and Development Group.
 
+### Example 3
+```powershell
+Set-AuthenticationPolicy -Identity "LegacyExchangeTokens" -BlockLegacyExchangeTokens
+```
+
+In Exchange Online, this example blocks legacy Exchange tokens from being issued to Outlook add-ins. The switch applies to the entire organization, and the Identity parameter must be set to the value "LegacyExchangeTokens". Specific authentication polices can't be applied.
+
 ## PARAMETERS
 
 ### -Identity
@@ -354,7 +361,17 @@ Accept wildcard characters: False
 ### -AllowLegacyExchangeTokens
 This parameter is available only in the cloud-based service.
 
-This parameter is reserved for internal Microsoft use.
+The AllowLegacyExchangeTokens switch specifies to allow legacy Exchange tokens to be issued to Outlook add-ins. You don't need to specify a value with this switch.
+
+Legacy Exchange tokens include Exchange user identity and callback tokens.
+
+The switch applies to the entire organization. The Identity parameter is required and must be set to the value "LegacyExchangeTokens". Specific authentication polices can't be applied.
+
+**Important**:
+
+- Apart from the Identity parameter, this switch disregards other authentication policy parameters used in the same command. We recommend running separate commands for other authentication policy changes.
+- It might take up to 24 hours for the change to take effect across your entire organization.
+- Legacy Exchange tokens will eventually be blocked by default in all cloud-based organizations. For more information, see [Nested app authentication and Outlook legacy tokens deprecation FAQ](https://learn.microsoft.com/office/dev/add-ins/outlook/faq-nested-app-auth-outlook-legacy-tokens#what-is-the-timeline-for-shutting-down-legacy-exchange-online-tokens).
 
 ```yaml
 Type: SwitchParameter
@@ -540,7 +557,19 @@ Accept wildcard characters: False
 ### -BlockLegacyExchangeTokens
 This parameter is available only in the cloud-based service.
 
-This parameter is reserved for internal Microsoft use.
+The BlockLegacyExchangeTokens switch specifies to block legacy Exchange tokens being issued to Outlook add-ins. You don't need to specify a value with this switch.
+
+Legacy Exchange tokens include Exchange user identity and callback tokens.
+
+The switch applies to the entire organization. The Identity parameter is required and must be set to the value "LegacyExchangeTokens". Specific authentication polices can't be applied.
+
+**Important**:
+
+- Apart from the Identity parameter, this switch disregards other authentication policy parameters used in the same command. We recommend running separate commands for other authentication policy changes.
+- It might take up to 24 hours for the change to take effect across your entire organization.
+- Legacy Exchange tokens issued to Outlook add-ins before token blocking was implemented in your organization will remain valid until they expire.
+- Blocking legacy Exchange tokens might cause some Microsoft add-ins to stop working. These add-ins are being updated to no longer use legacy tokens.
+- Legacy Exchange tokens will eventually be blocked by default in all cloud-based organizations. For more information, see [Nested app authentication and Outlook legacy tokens deprecation FAQ](https://learn.microsoft.com/office/dev/add-ins/outlook/faq-nested-app-auth-outlook-legacy-tokens#what-is-the-timeline-for-shutting-down-legacy-exchange-online-tokens).
 
 ```yaml
 Type: SwitchParameter
@@ -550,7 +579,7 @@ Applicable: Exchange Online, Exchange Online Protection
 
 Required: False
 Position: Named
-Default value: True
+Default value: False
 Accept pipeline input: False
 Accept wildcard characters: False
 ```