Procedures for Client Access Rules in Exchange Online

  • Article

Summary: Learn how to view, create, modify, delete, and test Client Access Rules in Exchange Online.

Client Access Rules allow or block client connections to your Exchange Online organization based on the properties of the connection. For more information about Client Access Rules, see Client Access Rules in Exchange Online.

Note

Beginning in October 2022, we've disabled access to client access rules for all existing Exchange Online organizations that weren't using them. In October 2023, support for client access rules will end for all Exchange Online organizations. For more information, see Deprecation of Client Access Rules in Exchange Online.

Verify that your rules work the way you expect. Be sure to thoroughly test each rule and the interactions between rules. For more information, see the Use Exchange Online PowerShell to test Client Access Rules section later in this topic.

What do you need to know before you begin?

  • Estimated time to complete each procedure: less than 5 minutes.

  • The procedures in this topic are only available in Exchange Online PowerShell. To learn how to use Windows PowerShell to connect to Exchange Online, see Connect to Exchange Online PowerShell.

  • Client Access Rules support IPv4 and IPv6 addresses. For more information about IPv6 addresses and syntax, see this Exchange 2013 topic: IPv6 address basics.

  • You need to be assigned permissions before you can perform this procedure or procedures. To see what permissions you need, see the "Mail flow" entry in Feature permissions in Exchange Online.

  • For information about keyboard shortcuts that may apply to the procedures in this topic, see Keyboard shortcuts for the Exchange admin center.

Tip

Having problems? Ask for help in the Exchange forums. Visit the forums at Exchange Online or Exchange Online Protection.

Use Exchange Online PowerShell to view Client Access Rules

To return a summary list of all Client Access Rules, run this command:

Get-ClientAccessRule

To return detailed information about a specific rule, use this syntax:

Get-ClientAccessRule -Identity "<RuleName>" | Format-List [<Specific properties to view>]

This example returns all the property values for the rule named "Block Client Connections from 192.168.1.0/24".

Get-ClientAccessRule -Identity "Block Client Connections from 192.168.1.0/24" | Format-List

This example returns only the specified properties for the same rule.

Get-ClientAccessRule -Identity "Block Client Connections from 192.168.1.0/24" | Format-List Name,Priority,Enabled,Scope,Action

For detailed syntax and parameter information, see Get-ClientAccessRule.

Use Exchange Online PowerShell to create Client Access Rules

To create Client Access Rules in Exchange Online PowerShell, use this syntax:

New-ClientAccessRule -Name "<RuleName>" [-Priority <PriorityValue>] [-Enabled <$true | $false>] -Action <AllowAccess | DenyAccess> [<Conditions>] [<Exceptions>]

This example creates a new Client Access Rule named Block ActiveSync that blocks access for Exchange ActiveSync clients, except for clients in the IP address range 192.168.10.1/24.

New-ClientAccessRule -Name "Block ActiveSync" -Action DenyAccess -AnyOfProtocols ExchangeActiveSync -ExceptAnyOfClientIPAddressesOrRanges 192.168.10.1/24

Notes:

  • As a best practice, create a Client Access Rule with the highest priority to preserve your administrator access to remote PowerShell. For example: New-ClientAccessRule -Name "Always Allow Remote PowerShell" -Action Allow -AnyOfProtocols RemotePowerShell -Priority 1.
  • The rule has the default priority value, because we didn't use the Priority parameter. For more information, see the Use Exchange Online PowerShell to set the priority of Client Access Rules section later in this topic.
  • The rule is enabled, because we didn't use the Enabled parameter, and the default value is $true.

This example creates a new Client Access Rule named Restrict EAC Access that blocks access for the Classic Exchange admin center, except if the client is coming from an IP address in the 192.168.10.1/24 range or if the user account name contains "tanyas".

New-ClientAccessRule -Name "Restrict EAC Access" -Action DenyAccess -AnyOfProtocols ExchangeAdminCenter -ExceptAnyOfClientIPAddressesOrRanges 192.168.10.1/24 -ExceptUsernameMatchesAnyOfPatterns *tanyas*

For detailed syntax and parameter information, see New-ClientAccessRule.

How do you know this worked?

To verify that you've successfully created a Client Access Rule, use any of these procedures:

  • Run this command in Exchange Online PowerShell to see the new rule in the list of rules:

    Get-ClientAccessRule

  • Replace <RuleName> with the name of the rule, and run this command to see the details of the rule:

    Get-ClientAccessRule -Identity "<RuleName>" | Format-List

  • See which Client Access Rules would affect a specific client connection to Exchange Online by using the Test-ClientAccessRule cmdlet. For more information, see the Use Exchange Online PowerShell to test Client Access Rules section later in this topic.

Use Exchange Online PowerShell to modify Client Access Rules

No additional settings are available when you modify a Client Access Rule. They're the same settings that were available when you created the rule.

To modify a Client Access Rule in Exchange Online PowerShell, use this syntax:

Set-ClientAccessRule -Identity "<RuleName>" [-Name "<NewName>"] [-Priority <PriorityValue>] [-Enabled <$true | $false>] -Action <AllowAccess | DenyAccess> [<Conditions>] [<Exceptions>]

This example disables the existing Client Access Rule named Allow IMAP4.

Set-ClientAccessRule -Identity "Allow IMAP4" -Enabled $false

An important consideration when you modify Client Access Rules is modifying conditions or exceptions that accept multiple values:

  • The values that you specify will replace any existing values.
  • To add or remove values without affecting other existing values, use this syntax: @{Add="<Value1>","<Value2>"...; Remove="<Value1>","<Value2>"...}

This example adds the IP address range 172.17.17.27/16 to the existing Client Access Rule named Allow IMAP4 without affecting the existing IP address values.

Set-ClientAccessRule -Identity "Allow IMAP4" -AnyOfClientIPAddressesOrRanges @{Add="172.17.17.27/16"}

For detailed syntax and parameter information, see Set-ClientAccessRule.

How do you know this worked?

To verify that you've successfully modified a Client Access Rule, use any of these procedures:

  • Replace <RuleName> with the name of the rule, and run this command to see the details of the rule:

    Get-ClientAccessRule -Identity "<RuleName>" | Format-List

  • See which Client Access Rules would affect a specific client connection to Exchange Online by using the Test-ClientAccessRule cmdlet. For more information, see the Use Exchange Online PowerShell to test Client Access Rules section later in this topic.

Use Exchange Online PowerShell to set the priority of Client Access Rules

By default, Client Access Rules are given a priority that's based on the order they were created in (newer rules are lower priority than older rules). A lower priority number indicates a higher priority for the rule, and rules are processed in priority order (higher priority rules are processed before lower priority rules). No two rules can have the same priority.

The highest priority you can set on a rule is 1. The lowest value you can set depends on the number of rules. For example, if you have five rules, you can use the priority values 1 through 5. Changing the priority of an existing rule can have a cascading effect on other rules. For example, if you have five rules (priorities 1 through 5), and you change the priority of a rule from 5 to 2, the existing rule with priority 2 is changed to priority 3, the rule with priority 3 is changed to priority 4, and the rule with priority 4 is changed to priority 5.

To set the priority of a Client Access Rule in Exchange Online PowerShell, use this syntax:

Set-ClientAccessRule -Identity "<RuleName>" -Priority <Number>

This example sets the priority of the rule named Disable IMAP4 to 2. All existing rules that have a priority less than or equal to 2 are decreased by 1 (their priority numbers are increased by 1).

Set-ClientAccessRule -Identity "Disable IMAP" -Priority 2

Note: To set the priority of a new rule when you create it, use the Priority parameter on the New-ClientAccessRule cmdlet.

How do you know this worked?

To verify that you've successfully set the priority of a Client Access Rule, use either of these procedures:

  • Run the this command in Exchange Online PowerShell to see the list of rules and their Priority values:

    Get-ClientAccessRule

  • Replace <RuleName> with the name of the rule, and run this command:

    Get-ClientAccessRule -Identity "<RuleName>" | Format-List Name,Priority

Use Exchange Online PowerShell to remove Client Access Rules

To remove Client Access Rules in Exchange Online PowerShell, use this syntax:

Remove-ClientAccessRule -Identity "<RuleName>"

This example removes the Client Access Rule named Block POP3.

Remove-ClientAccessRule -Identity "Block POP3"

Note: To disable a Client Access Rule without deleting it, use the Enabled parameter with the value $false on the Set-ClientAccessRule cmdlet.

For detailed syntax and parameter information, see Remove-ClientAccessRule.

How do you know this worked?

To verify that you've successfully removed a Client Access Rule, run this command in Exchange Online PowerShell to verify that the rule is no longer listed:

Get-ClientAccessRule

Use Exchange Online PowerShell to test Client Access Rules

To see which Client Access Rules would affect a specific client connection to Exchange Online, use this syntax:

Test-ClientAccessRule -User <MailboxIdentity> -AuthenticationType <AuthenticationType> -Protocol <Protocol> -RemoteAddress <ClientIPAddress> -RemotePort <TCPPortNumber>

This example returns the Client Access Rules that would match a client connection to Exchange Online that has these properties:

  • Authentication type: Basic
  • Protocol: OutlookWebApp
  • Remote address: 172.17.17.26
  • Remote port: 443
  • User: julia@contoso.com
Test-ClientAccessRule -User julia@contoso.com -AuthenticationType BasicAuthentication -Protocol OutlookWebApp -RemoteAddress 172.17.17.26 -RemotePort 443

For detailed syntax and parameter information, see Test-ClientAccessRule.