Updates due to customer escalations.

Author: briandaymsft

exchange/exchange-ps/exchange/New-ClientAccessRule.md

@@ -12,6 +12,7 @@ ms.reviewer:
 # New-ClientAccessRule
 
 ## SYNOPSIS
+
 This cmdlet is functional only in Exchange Server 2019 and in the cloud-based service. Some parameters and settings may be exclusive to one environment or the other.
 
 Use the New-ClientAccessRule cmdlet to create client access rules. Client access rules help you control access to your organization based on the properties of the connection.
@@ -20,7 +21,7 @@ For information about the parameter sets in the Syntax section below, see [Excha
 
 ## SYNTAX
 
-```
+```powershell
 New-ClientAccessRule [-Name] <String> -Action <ClientAccessRulesAction>
  [-AnyOfAuthenticationTypes <MultiValuedProperty>]
  [-AnyOfClientIPAddressesOrRanges <MultiValuedProperty>]
@@ -45,29 +46,41 @@ New-ClientAccessRule [-Name] <String> -Action <ClientAccessRulesAction>
 ```
 
 ## DESCRIPTION
-Client access rules are like mail flow rules (also known as transport rules) for client connections to your organization. You use conditions and exceptions to identify the connections based on their properties, and actions that allow or block the connections.
 
-**Note**: Currently, not all authentication types are supported for all protocols. The supported authentication types per protocol are described in this list:
+Client access rules are like mail flow rules (also known as transport rules) for client connections to your organization. You use conditions and exceptions to identify the connections based on their properties, and actions that allow or block the connections.
 
-- ExchangeActiveSync: BasicAuthentication, OAuthAuthentication, and CertificateBasedAuthentication.
-- ExchangeAdminCenter: BasicAuthentication and AdfsAuthentication.
-- IMAP4: BasicAuthentication and OAuthAuthentication.
-- OutlookWebApp: BasicAuthentication and AdfsAuthentication.
-- POP3: BasicAuthentication and OAuthAuthentication.
-- RemotePowerShell: BasicAuthentication and NonBasicAuthentication.
+**Note**: Not all protocols support authentication type filters. Additionally, not all authentication types are supported for each protocol where authentication filters are supported. The supported authentication types per protocol are in the following table. Please use caution when mixing protocol and authentication types in the same rule.
+
+|Protocol|Auth filter supported|BasicAuthentication|OAuthAuthentication|AdfsAuthentication|CertificateBasedAuthentication|NonBasicAuthentication|
+|---|:---:|:---:|:---:|:---:|:---:|:---:|
+|ExchangeActiveSync|Yes|Yes|Yes|No|Yes|No|
+|ExchangeAdminCenter|Yes|Yes|No|Yes|No|No|
+|ExchangeWebServices|No|N/A|N/A|N/A|N/A|N/A|
+|IMAP4|Yes|Yes|Yes|No|No|No|
+|OfflineAddressBook|No|N/A|N/A|N/A|N/A|N/A|
+|OutlookAnywhere|No|N/A|N/A|N/A|N/A|N/A|
+|OutlookWebApp|Yes|Yes|No|Yes|No|No|
+|POP3|Yes|Yes|Yes|No|No|No|
+|PowerShellWebServices|No|N/A|N/A|N/A|N/A|N/A|
+|RemotePowerShell|Yes|Yes|No|No|No|Yes|
+|REST|No|N/A|N/A|N/A|N/A|N/A|
+|UniversalOutlook|No|N/A|N/A|N/A|N/A|N/A|
+||||||||
 
 You need to be assigned permissions before you can run this cmdlet. Although this topic lists all parameters for the cmdlet, you may not have access to some parameters if they're not included in the permissions assigned to you. To find the permissions required to run any cmdlet or parameter in your organization, see [Find the permissions required to run any Exchange cmdlet](https://docs.microsoft.com/powershell/exchange/find-exchange-cmdlet-permissions).
 
 ## EXAMPLES
 
 ### Example 1
+
 ```powershell
 New-ClientAccessRule -Name AllowRemotePS -Action Allow -AnyOfProtocols RemotePowerShell -Priority 1
 ```
 
 This example creates a highest priority rule that allows access to remote PowerShell. This rule is an important safeguard to preserve access to your organization. Without this rule, if you create rules that block your access to remote PowerShell, or that block all protocols for everyone, you'll lose the ability to fix the rules yourself (you'll need to call Microsoft Customer Service and Support).
 
 ### Example 2
+
 ```powershell
 New-ClientAccessRule -Name "Block ActiveSync" -Action DenyAccess -AnyOfProtocols ExchangeActiveSync -ExceptAnyOfClientIPAddressesOrRanges 192.168.10.1/24
 ```
@@ -77,6 +90,7 @@ This example creates a new client access rule named Block ActiveSync that blocks
 ## PARAMETERS
 
 ### -Action
+
 The Action parameter specifies the action for the client access rule. Valid values for this parameter are AllowAccess and DenyAccess.
 
 ```yaml
@@ -93,6 +107,7 @@ Accept wildcard characters: False
 ```
 
 ### -Name
+
 The Name parameter specifies a unique name for the client access rule.
 
 ```yaml
@@ -109,6 +124,7 @@ Accept wildcard characters: False
 ```
 
 ### -AnyOfAuthenticationTypes
+
 This parameter is functional only in the cloud-based service.
 
 The AnyOfAuthenticationTypes parameter specifies a condition for the client access rule that's based on the client's authentication type.
@@ -123,6 +139,8 @@ Valid values for this parameter are:
 
 You can enter multiple values separated by commas. Don't use quotation marks.
 
+**Note**: Please refer to the table in the beginning of this article to understand what authentication types may be used with what protocols.
+
 ```yaml
 Type: MultiValuedProperty
 Parameter Sets: (All)
@@ -137,6 +155,7 @@ Accept wildcard characters: False
 ```
 
 ### -AnyOfClientIPAddressesOrRanges
+
 The AnyOfClientIPAddressesOrRanges parameter specifies a condition for the client access rule that's based on the client's IPv4 or IPv6 address. Valid values are:
 
 - Single IP address: For example, 192.168.1.1 or 2001:DB8::2AA:FF:C0A8:640A.
@@ -161,6 +180,7 @@ Accept wildcard characters: False
 ```
 
 ### -AnyOfProtocols
+
 The AnyOfProtocols parameter specifies a condition for the client access rule that's based on the client's protocol.
 
 Valid values for this parameter are:
@@ -196,6 +216,7 @@ Accept wildcard characters: False
 ```
 
 ### -AnyOfSourceTcpPortNumbers
+
 This parameter is reserved for internal Microsoft use.
 
 ```yaml
@@ -212,6 +233,7 @@ Accept wildcard characters: False
 ```
 
 ### -Confirm
+
 The Confirm switch specifies whether to show or hide the confirmation prompt. How this switch affects the cmdlet depends on if the cmdlet requires confirmation before proceeding.
 
 - Destructive cmdlets (for example, Remove-\* cmdlets) have a built-in pause that forces you to acknowledge the command before proceeding. For these cmdlets, you can skip the confirmation prompt by using this exact syntax: `-Confirm:$false`.
@@ -231,6 +253,7 @@ Accept wildcard characters: False
 ```
 
 ### -DomainController
+
 This parameter is available only in on-premises Exchange.
 
 The DomainController parameter specifies the ___domain controller that's used by this cmdlet to read data from or write data to Active Directory. You identify the ___domain controller by its fully qualified ___domain name (FQDN). For example, dc01.contoso.com.
@@ -249,6 +272,7 @@ Accept wildcard characters: False
 ```
 
 ### -Enabled
+
 The Enabled parameter specifies whether the client access rule is enabled or disabled. Valid values for this parameter are $true or $false. The default value is $true.
 
 ```yaml
@@ -265,6 +289,7 @@ Accept wildcard characters: False
 ```
 
 ### -ExceptAnyOfAuthenticationTypes
+
 This parameter is functional only in the cloud-based service.
 
 The ExceptAnyOfAuthenticationTypes parameter specifies an exception for the client access rule that's based on the client's authentication type.
@@ -279,6 +304,8 @@ Valid values for this parameter are:
 
 You can enter multiple values separated by commas. Don't use quotation marks.
 
+**Note**: Please refer to the table in the beginning of this article to understand what authentication types may be used with what protocols.
+
 ```yaml
 Type: MultiValuedProperty
 Parameter Sets: (All)
@@ -293,6 +320,7 @@ Accept wildcard characters: False
 ```
 
 ### -ExceptAnyOfClientIPAddressesOrRanges
+
 The ExceptAnyOfClientIPAddressesOrRanges parameter specifies an exception for the client access rule that's based on the client's IPv4 or IPv6 address. Valid values are:
 
 - Single IP address: For example, 192.168.1.1 or 2001:DB8::2AA:FF:C0A8:640A.
@@ -317,6 +345,7 @@ Accept wildcard characters: False
 ```
 
 ### -ExceptAnyOfProtocols
+
 This parameter is functional only in the cloud-based service.
 
 The ExceptAnyOfProtocols parameter specifies an exception for the client access rule that's based on the client's protocol.
@@ -352,6 +381,7 @@ Accept wildcard characters: False
 ```
 
 ### -ExceptAnyOfSourceTcpPortNumbers
+
 This parameter is reserved for internal Microsoft use.
 
 ```yaml
@@ -368,6 +398,7 @@ Accept wildcard characters: False
 ```
 
 ### -ExceptUserIsMemberOf
+
 This parameter is reserved for internal Microsoft use.
 
 ```yaml
@@ -384,6 +415,7 @@ Accept wildcard characters: False
 ```
 
 ### -ExceptUsernameMatchesAnyOfPatterns
+
 This parameter is functional only in the cloud-based service.
 
 The ExceptUsernameMatchesAnyOfPatterns parameter specifies an exception for the client access rule that's based on the user's account name in the format `<Domain>\<UserName>` (for example, `contoso.com\jeff`). This parameter accepts text and the wildcard character (\*) (for example, `*jeff*`, but not `jeff*`). Non-alphanumeric characters don't require an escape character.
@@ -404,6 +436,7 @@ Accept wildcard characters: False
 ```
 
 ### -Priority
+
 The Priority parameter specifies a priority value for the rule that determines the order of rule processing. A lower integer value indicates a higher priority, the value 0 is the highest priority, and rules can't have the same priority value.
 
 Valid values and the default value for this parameter depend on the number of existing rules. For example, if there are 8 existing rules:
@@ -428,6 +461,7 @@ Accept wildcard characters: False
 ```
 
 ### -Scope
+
 The Scope parameter specifies the scope of the client access rule. Valid values are:
 
 - Users: The rule only applies to end-user connections.
@@ -447,6 +481,7 @@ Accept wildcard characters: False
 ```
 
 ### -UserIsMemberOf
+
 This parameter is reserved for internal Microsoft use.
 
 ```yaml
@@ -463,6 +498,7 @@ Accept wildcard characters: False
 ```
 
 ### -UsernameMatchesAnyOfPatterns
+
 This parameter is functional only in the cloud-based service.
 
 The UsernameMatchesAnyOfPatterns parameter specifies a condition for the client access rule that's based on the user's account name in the format `<Domain>\<UserName>` (for example, `contoso.com\jeff`). This parameter accepts text and the wildcard character (\*) (for example, `*jeff*`, but not `jeff*`). Non-alphanumeric characters don't require an escape character. This parameter does not work with the -AnyOfProtocols UniversalOutlook parameter.
@@ -483,31 +519,42 @@ Accept wildcard characters: True
 ```
 
 ### -UserRecipientFilter
-This parameter is functional only in the cloud-based service.
 
-The UserRecipientFilter parameter specifies a condition for the client access rule that uses OPath filter syntax to identify the user. The syntax is `"Property -ComparisonOperator 'Value'"` (for example, `"City -eq 'Redmond'"`).
-
-- Enclose the whole OPath filter in double quotation marks " ". If the filter contains system values (for example, `$true`, `$false`, or `$null`), use single quotation marks ' ' instead. Although this parameter is a string (not a system block), you can also use braces { }, but only if the filter doesn't contain variables.
-- Property is a filterable property. For filterable recipient properties, see [Filterable properties for the RecipientFilter parameter on Exchange cmdlets](https://docs.microsoft.com/powershell/exchange/recipientfilter-properties).
-- ComparisonOperator is an OPath comparison operator (for example `-eq` for equals and `-like` for string comparison). For more information about comparison operators, see [about_Comparison_Operators](https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_comparison_operators).
-- Value is the property value to search for. Enclose text values and variables in single quotation marks (`'Value'` or `'$Variable'`). If a variable value contains single quotation marks, you need to identify (escape) the single quotation marks to expand the variable correctly. For example, instead of `'$User'`, use `'$($User -Replace "'","''")'`. Don't enclose integers or system values (for example, `500`, `$true`, `$false`, or `$null`).
-
-You can chain multiple search criteria together using the logical operators `-and` and `-or`. For example, `"Criteria1 -and Criteria2"` or `"(Criteria1 -and Criteria2) -or Criteria3"`.
+This parameter is functional only in the cloud-based service.
 
-For detailed information about OPath filters in Exchange, see [Additional OPATH syntax information](https://docs.microsoft.com/powershell/exchange/recipient-filters#additional-opath-syntax-information).
+The UserRecipientFilter parameter specifies a condition for the client access rule that uses OPath filter syntax to identify the user based on a limited set of attributes.
 
-The filterable properties that you can use with this parameter are:
+The filterable properties that you can use with this parameter are limited to the list below. Client Access Rules do not support the full list of recipient filters used by other features.
 
 - City
 - Company
-- CountryOrRegion
+- CountryOrRegion (ISO 3166-1 alpha-2 code for the country must be used.)
 - CustomAttribute1 to CustomAttribute15
 - Department
 - Office
 - PostalCode
 - StateOrProvince
 - StreetAddress
 
+The syntax is `"Property -ComparisonOperator 'Value'"`
+
+An example would be `"City -eq 'Redmond'"`
+
+Another example would be  `"CountryOrRegion -eq 'SG'"`
+
+- Property is one of the filterable properties in the list above (for example `City` or `CustomAttribute1`).
+- ComparisonOperator is an OPath comparison operator (for example `-eq` for equals and `-like` for string comparison). For more information about comparison operators, see [about_Comparison_Operators](https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_comparison_operators).
+- Value is the property value to search for. Enclose text values and variables in single quotation marks (`'Value'` or `'$Variable'`). If a variable value contains single quotation marks, you need to identify (escape) the single quotation marks to expand the variable correctly. For example, instead of `'$User'`, use `'$($User -Replace "'","''")'`. Do not enclose integers or system values (for example, `500`, `$true`, `$false`, or `$null` are all proper uses).
+- Enclose the whole OPath filter in double quotation marks " ". If the filter contains system values (for example, `$true`, `$false`, or `$null`), use single quotation marks ' ' instead. Although this parameter is a string (not a system block), you can also use braces { }, but only if the filter doesn't contain variables.
+
+You can chain multiple search criteria together using the logical operators `-and` and `-or`.
+
+An example would be, `"CustomAttribute1 -eq 'AllowOWA' -and CountryOrRegion -eq AU'"`
+
+Another example would be, `"(CountryOrRegion -eq 'US' -and Department -eq 'Sales') -or Department -eq 'Research'"`.
+
+For detailed information about OPath filter syntax in Exchange, see [Additional OPATH syntax information](https://docs.microsoft.com/powershell/exchange/recipient-filters#additional-opath-syntax-information).
+
 ```yaml
 Type: String
 Parameter Sets: (All)
@@ -522,6 +569,7 @@ Accept wildcard characters: False
 ```
 
 ### -WhatIf
+
 The WhatIf switch simulates the actions of the command. You can use this switch to view the changes that would occur without actually applying those changes. You don't need to specify a value with this switch.
 
 ```yaml
@@ -538,16 +586,15 @@ Accept wildcard characters: False
 ```
 
 ### CommonParameters
+
 This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/p/?LinkID=113216).
 
 ## INPUTS
 
-###  
 To see the input types that this cmdlet accepts, see [Cmdlet Input and Output Types](https://go.microsoft.com/fwlink/p/?linkId=616387). If the Input Type field for a cmdlet is blank, the cmdlet doesn't accept input data.
 
 ## OUTPUTS
 
-###  
 To see the return types, which are also known as output types, that this cmdlet accepts, see [Cmdlet Input and Output Types](https://go.microsoft.com/fwlink/p/?linkId=616387). If the Output Type field is blank, the cmdlet doesn't return data.
 
 ## NOTES