Manage URLs in the Tenant Allow/Block List

Important

Welcome to Microsoft Defender for Office 365, the new name for Office 365 Advanced Threat Protection. Read more about this and other updates here. We'll be updating names in products and in the docs in the near future.

Note

The features described in this topic are in Preview, are subject to change, and are not available in all organizations.

In Microsoft 365 organizations with mailboxes in Exchange Online or standalone Exchange Online Protection (EOP) organizations without Exchange Online mailboxes, you might disagree with the EOP filtering verdict. For example, a good message might be marked as bad (a false positive), or a bad message might be allowed through (a false negative).

The Tenant Allow/Block List in the Security & Compliance Center gives you a way to manually override the Microsoft 365 filtering verdicts. The Tenant Allow/Block List is used during mail flow and at the time of user clicks. You can specify URLs to allow or block in the Tenant Allow/Block List.

This topic describes how to configure entries in the Tenant Allow/Block List in the Security & Compliance Center or in PowerShell (Exchange Online PowerShell for Microsoft 365 organizations with mailboxes in Exchange Online; standalone EOP PowerShell for organizations without Exchange Online mailboxes).

What do you need to know before you begin?

Use the Security & Compliance Center to create URL entries in the Tenant Allow/Block List

For details about the syntax for URL entries, see the URL syntax for the Tenant Allow/Block List section later in this topic.

  1. In the Security & Compliance Center, go to Threat management > Policy > Tenant Allow/Block Lists.

  2. On the Tenant Allow/Block List page, verify that the URLs tab is selected, and then click Add

  3. In the Add new URLs flyout that appears, configure the following settings:

    • Add URLs with wildcards: Enter one URL per line, up to a maximum of 20.

    • Block/Allow: Select whether you want to Allow or Block the specified URLs.

    • Never expire: Do one of the following steps:

      • Verify the setting is turned off (Toggle off) and use the Expires on box to specify the expiration date for the entries.

      or

      • Move the toggle to the right to configure the entries to never expire: Toggle on.
    • Optional note: Enter descriptive text for the entries.

  4. When you're finished, click Add.

Use the Security & Compliance Center to view entries in the Tenant Allow/Block List

  1. In the Security & Compliance Center, go to Threat management > Policy > Tenant Allow/Block Lists.

  2. Select the URLs tab.

Click on the following column headings to sort in ascending or descending order:

  • Value
  • Action: Block or Allow.
  • Last updated date
  • Expiration date
  • Note

Click Group to group the entries by Action (Block or Allow) or None.

Click Search, enter all or part of a value, and then press ENTER to find a specific value. When you're finished, click Clear search Clear search icon.

Click Filter. In the Filter flyout that appears, configure any of the following settings:

  • Action: Select Allow, Block or both.

  • Never expire: Select off (Toggle off) or on (Toggle on).

  • Last updated: Select a start date (From), an end date (To) or both.

  • Expiration date: Select a start date (From), an end date (To) or both.

When you're finished, click Apply.

To clear existing filters, click Filter, and in the Filter flyout that appears, click Clear filters.

Use the Security & Compliance Center to modify entries in the Tenant Allow/Block List

You can't modify the URL value itself. Instead, you need to delete the entry and recreate it.

  1. In the Security & Compliance Center, go to Threat management > Policy > Tenant Allow/Block Lists.

  2. Select the URLs tab.

  3. Select the entry that you want to modify, and then click Edit Edit icon.

  4. In the flyout that appears, configure the following settings:

    • Block/Allow: Select Allow or Block.

    • Never expire: Do one of the following steps:

      • Verify the setting is turned off (Toggle off) and use the Expires on box to specify the expiration date for the entry.

      or

      • Move the toggle to the right to configure the entry to never expire: Toggle on.
    • Optional note: Enter descriptive text for the entry.

  5. When you're finished, click Save.

Use the Security & Compliance Center to remove entries from the Tenant Allow/Block List

  1. In the Security & Compliance Center, go to Threat management > Policy > Tenant Allow/Block Lists.

  2. Select the URLs tab.

  3. Select the entry that you want to remove, and then click Delete Delete icon.

  4. In the warning dialog that appears, click Delete.

Use Exchange Online PowerShell or standalone EOP PowerShell to configure the Tenant Allow/Block List

Use PowerShell to add entries in the Tenant Allow/Block List

To add entries in the Tenant Allow/Block List, use the following syntax:

New-TenantAllowBlockListItems -ListType Url -Action <Allow | Block> -Entries <String[]> [-ExpirationDate <DateTime>] [-NoExpiration] [-Notes <String>]

This example adds a URL block entry for contoso.com and all subdomains (for example, contoso.com, www.contoso.com, and xyz.abc.contoso.com). Because we didn't use the ExpirationDate or NoExpiration parameters, the entry expires after 30 days.

New-TenantAllowBlockListItem -ListType Url -Action Block -Entries ~contoso.com

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

Use PowerShell to view entries in the Tenant Allow/Block List

To view entries in the Tenant Allow/Block List, use the following syntax:

Get-TenantAllowBlockListItems -ListType Url [-Entry <URLValue>] [-Action <Allow | Block>] [-ExpirationDate <DateTime>] [-NoExpiration]

This example returns all blocked URLs.

Get-TenantAllowBlockListItems -ListType Url -Action Block

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

Use PowerShell to modify entries in the Tenant Allow/Block List

You can't modify the URL value itself. Instead, you need to delete the entry and recreate it.

To modify entries in the Tenant Allow/Block List, use the following syntax:

Set-TenantAllowBlockListItems -ListType Url -Ids <"Id1","Id2",..."IdN"> [-Action <Allow | Block>] [-ExpirationDate <DateTime>] [-NoExpiration] [-Notes <String>]

This example changes the expiration date of the specified entry.

Set-TenantAllowBlockListItems -ListType Url -Ids "RgAAAAAI8gSyI_NmQqzeh-HXJBywBwCqfQNJY8hBTbdlKFkv6BcUAAAl_QCZAACqfQNJY8hBTbdlKFkv6BcUAAAl_oSRAAAA" -ExpirationDate (Get-Date "5/30/2020 9:30 AM").ToUniversalTime()

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

Use PowerShell to remove entries from the Tenant Allow/Block List

To remove entries from the Tenant Allow/Block List, use the following syntax:

Remove-TenantAllowBlockListItems -ListType Url -Ids <"Id1","Id2",..."IdN">

This example removes the specified URL entry from the Tenant Allow/Block List.

Remove-TenantAllowBlockListItems -ListType Url -Ids "RgAAAAAI8gSyI_NmQqzeh-HXJBywBwCqfQNJY8hBTbdlKFkv6BcUAAAl_QCZAACqfQNJY8hBTbdlKFkv6BcUAAAl_oSPAAAA0"

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

URL syntax for the Tenant Allow/Block List

  • IP4v and IPv6 addresses are allowed, but TCP/UDP ports are not.

  • Filename extensions are not allowed (for example, test.pdf).

  • Unicode is not supported, but Punycode is.

  • Hostnames are allowed if all of the following statements are true:

    • The hostname contains a period.
    • There is at least one character to the left of the period.
    • There are at least two characters to the right of the period.

    For example, t.co is allowed; .com or contoso. are not allowed.

  • Subpaths are not implied.

    For example, contoso.com does not include contoso.com/a.

  • Wildcards (*) are allowed in the following scenarios:

    • A left wildcard must be followed by a period to specify a subdomain.

      For example, *.contoso.com is allowed; *contoso.com is not allowed.

    • A right wildcard must follow a forward slash (/) to specify a path.

      For example, contoso.com/* is allowed; contoso.com* or contoso.com/ab* are not allowed.

    • All subpaths are not implied by a right wildcard.

      For example, contoso.com/* does not include contoso.com/a.

    • *.com* is invalid (not a resolvable domain and the right wildcard does not follow a forward slash).

    • Wildcards are not allowed in IP addresses.

  • The tilde (~) character is available in the following scenarios:

    • A left tilde implies a domain and all subdomains.

      For example ~contoso.com includes contoso.com and *.contoso.com.

  • URL entries that contain protocols (for example, http://, https://, or ftp://) will fail, because URL entries apply to all protocols.

  • A username or password aren't supported or required.

  • Quotes (' or ") are invalid characters.

  • A URL should include all redirects where possible.

URL entry scenarios

Valid URL entries and their results are described in the following sections.

Scenario: No wildcards

Entry: contoso.com

Scenario: Left wildcard (subdomain)

Entry: *.contoso.com

  • Allow match and Block match:

  • Allow not matched and Block not matched:

Scenario: Right wildcard at top of path

Entry: contoso.com/a/*

Scenario: Left tilde

Entry: ~contoso.com

  • Allow match and Block match:

  • Allow not matched and Block not matched:

Scenario: Right wildcard suffix

Entry: contoso.com/*

  • Allow match and Block match:

    • contoso.com/?q=whatever@fabrikam.com
    • contoso.com/a
    • contoso.com/a/b/c
    • contoso.com/ab
    • contoso.com/b
    • contoso.com/b/a/c
    • contoso.com/ba
  • Allow not matched and Block not matched: contoso.com

Scenario: Left wildcard subdomain and right wildcard suffix

Entry: *.contoso.com/*

Scenario: Left and right tilde

Entry: ~contoso.com~

  • Allow match and Block match:

  • Allow not matched and Block not matched:

    • 123contoso.com
    • contoso.org

Scenario: IP address

Entry: 1.2.3.4

  • Allow match and Block match: 1.2.3.4

  • Allow not matched and Block not matched:

    • 1.2.3.4/a
    • 11.2.3.4/a

IP address with right wildcard

Entry: 1.2.3.4/*

  • Allow match and Block match:

    • 1.2.3.4/b
    • 1.2.3.4/baaaa

Examples of invalid entries

The following entries are invalid:

  • Missing or invalid domain values:

    • contoso
    • *.contoso.*
    • *.com
    • *.pdf
  • Wildcard on text or without spacing characters:

    • *contoso.com
    • contoso.com*
    • *1.2.3.4
    • 1.2.3.4*
    • contoso.com/a*
    • contoso.com/ab*
  • IP addresses with ports:

    • contoso.com:443
    • abc.contoso.com:25
  • Non-descriptive wildcards:

    • *
    • *.*
  • Middle wildcards:

    • conto*so.com
    • conto~so.com
  • Double wildcards

    • contoso.com/**
    • contoso.com/*/*