Allow or block URLs using the Tenant Allow/Block List
Tip
Did you know you can try the features in Microsoft 365 Defender for Office 365 Plan 2 for free? Use the 90-day Defender for Office 365 trial at the Microsoft 365 Defender portal trials hub. Learn about who can sign up and trial terms here.
Applies to
- Exchange Online Protection
- Microsoft Defender for Office 365 plan 1 and plan 2
- Microsoft 365 Defender
Important
To allow phishing URLs that are part of third-party attack simulation training, use the advanced delivery configuration to specify the URLs. Don't use the Tenant Allow/Block List.
This article describes how to create and manage URL allow and block entries that are available in the Tenant Allow/Block List. For more information about the Tenant Allow/Block List, see Manage allows and blocks in the Tenant Allow/Block List.
You manage allow and block entries for URLs in the Microsoft 365 Defender Portal or in Exchange Online PowerShell.
What do you need to know before you begin?
You open the Microsoft 365 Defender portal at https://security.microsoft.com. To go directly to the Tenant Allow/Block List page, use https://security.microsoft.com/tenantAllowBlockList. To go directly to the Submissions page, use https://security.microsoft.com/reportsubmission.
To connect to Exchange Online PowerShell, see Connect to Exchange Online PowerShell. To connect to standalone EOP PowerShell, see Connect to Exchange Online Protection PowerShell.
For URL entry syntax, see the URL syntax for the Tenant Allow/Block List section later in this article.
For URLs, the maximum number of allow entries is 500, and the maximum number of block entries is 500 (1000 URL entries total).
You can enter a maximum of 250 characters in a URL entry.
An entry should be active within 30 minutes, but it might take up to 24 hours for the entry to be active.
You need to be assigned permissions before you can do the procedures in this article. You have the following options:
- Microsoft 365 Defender role based access control (RBAC): configuration/security (manage) or configuration/security (read). Currently, this option requires membership in the Microsoft 365 Defender Preview program.
- Exchange Online RBAC:
- Add and remove entries from the Tenant Allow/Block List: Membership in one of the following role groups:
- Organization Management or Security Administrator (Security admin role).
- Security Operator (Tenant AllowBlockList Manager).
- Read-only access to the Tenant Allow/Block List: Membership in one of the following role groups:
- Global Reader
- Security Reader
- View-Only Configuration
- View-Only Organization Management
- Add and remove entries from the Tenant Allow/Block List: Membership in one of the following role groups:
- Azure AD RBAC: Membership in the Global Administrator, Security Administrator, Global Reader, or Security Reader roles gives users the required permissions and permissions for other features in Microsoft 365.
Create block entries for URLs
Email messages that contain these blocked URLs are blocked as high confidence phishing. Messages containing the blocked URLs are quarantined.
You have the following options to create block entries for URLs:
- The Submissions page in the Microsoft 365 Defender portal
- The Tenant Allow/Block List in the Microsoft 365 Defender portal or in PowerShell
Use the Microsoft 365 Defender portal to create block entries for URLs on the Submissions page
When you use the Submissions page at https://security.microsoft.com/reportsubmission to submit URLs as Should have been blocked (False negative), you can select Block this URL to add a block entry on the URLs tab in the Tenant Allow/Block List.
For instructions, see Submit questionable URLs to Microsoft.
Use the Microsoft 365 Defender portal to create block entries for URLs in the Tenant Allow/Block List
You can create block entries for URLs directly in the Tenant Allow/Block List.
In the Microsoft 365 Defender portal at https://security.microsoft.com, go to Policies & rules > Threat Policies > Rules section > Tenant Allow/Block Lists. Or, to go directly to the Tenant Allow/Block List page, use https://security.microsoft.com/tenantAllowBlockList.
On the Tenant Allow/Block List page, select the URLs tab.
On the URLs tab, click
Block.
In the Block URLs flyout that appears, configure the following settings:
Add URLs with wildcards: Enter one URL per line, up to a maximum of 20. For details about the syntax for URL entries, see the URL syntax for the Tenant Allow/Block List section later in this article.
Remove block entry after: The default value is 30 days, but you can select from the following values:
- Never expire
- 1 day
- 7 days
- 30 days
- Specific date: The maximum value is 90 days from today.
Optional note: Enter descriptive text for why you're blocking the URLs.
When you're finished, click Add.
Use PowerShell to create block entries for URLs in the Tenant Allow/Block List
In Exchange Online PowerShell, use the following syntax:
New-TenantAllowBlockListItems -ListType Url -Block -Entries "Value1","Value2",..."ValueN" <-ExpirationDate <Date> | -NoExpiration> [-Notes <String>]
This example adds a block entry for the URL contoso.com and all subdomains (for example, contoso.com and xyz.abc.contoso.com). Because we didn't use the ExpirationDate or NoExpiration parameters, the entry expires after 30 days.
New-TenantAllowBlockListItems -ListType Url -Block -Entries ~contoso.com
For detailed syntax and parameter information, see New-TenantAllowBlockListItems.
Use the Microsoft 365 Defender portal to create allow entries for URLs on the Submissions page
You can't create URL allow entries directly in the Tenant Allow/Block List. Instead, you use the Submissions page at https://security.microsoft.com/reportsubmission to submit the URL as a false positive, which also adds an allow entry on the URLs tab in the Tenant Allow/Block List.
For instructions, see Submit good URLs to Microsoft.
Important
Microsoft does not allow you to create allow entries directly. Unnecessary allow entries expose your organization to malicious email which could have been filtered by the system.
Microsoft manages the allow entry creation process for URLs from the Submissions page. We'll create allow entries for URLs that were determined to be malicious by our filters during mail flow or at time of click.
We allow subsequent messages that contain variations of the original URL. For example, you use the Submissions page to report the incorrectly blocked URL www.contoso.com/abc
. If your organization later receives a message that contains the URL (for example but not limited to: www.contoso.com/abc
, www.contoso.com/abc?id=1
, www.contoso.com/abc/def/gty/uyt?id=5
, or *.contoso.com/abc
), the message won't be blocked based on the URL. In other words, you don't need to report multiple variations of the same URL as good to Microsoft.
When the URL is encountered again, all filters associated with the URL are overridden.
By default, allow entries for URLs exist for 30 days. During those 30 days, Microsoft will learn from the allow entries and remove them or automatically extend them. After Microsoft learns from the removed allow entries, messages that contain those URLs will be delivered, unless something else in the message is detected as malicious.
During mail flow, if messages containing the allowed URL pass other checks in the filtering stack, the messages will be delivered. For example, if a message passes email authentication checks and file filtering, a message containing an allowed URL will be delivered.
During time of click, the URL allow entry overrides all filters associated with the URL entity, allowing the user to access the content in the URL.
Adding an allow entry for a URL does not prevent it from being wrapped by Safe Links. For more information, see Do not rewrite list in SafeLinks.
Use the Microsoft 365 Defender portal to view existing allow or block entries for URLs in the Tenant Allow/Block List
In the Microsoft 365 Defender portal at https://security.microsoft.com, go to Policies & rules > Threat Policies > Tenant Allow/Block Lists in the Rules section. Or, to go directly to the Tenant Allow/Block Lists page, use https://security.microsoft.com/tenantAllowBlockList.
Select the URL tab. The following columns are available:
- Value: The URL.
- Action: The values are Allow or Block.
- Modified by
- Last updated
- Remove on: The expiration date.
- Notes
Click on a column heading to sort in ascending or descending order.
Click
Group to group the results by None or Action.
Click
Search, enter all or part of a value, and then press the ENTER key to find a specific value. When you're finished, click
to clear the search.
Click
Filter to filter the results. The following values are available in the Filter flyout that appears:
- Action: The values are Allow and Block.
- Never expire:
or
- Last updated: Select From and To dates.
- Remove on: Select From and To dates.
When you're finished, click Apply. To clear existing filters, click
Clear filters in the Filter flyout.
Use PowerShell to view existing allow or block entries for URLs in the Tenant Allow/Block List
In Exchange Online PowerShell, use the following syntax:
Get-TenantAllowBlockListItems -ListType Url [-Allow] [-Block] [-Entry <URLValue>] [<-ExpirationDate <Date> | -NoExpiration>]
This example returns all allowed and blocked URLs.
Get-TenantAllowBlockListItems -ListType Url
This example filters the results by blocked URLs.
Get-TenantAllowBlockListItems -ListType Url -Block
For detailed syntax and parameter information, see Get-TenantAllowBlockListItems.
Use the Microsoft 365 Defender portal to modify existing allow or block entries for URLs in the Tenant Allow/Block List
You can make the following modifications to entries for URLs in the Tenant Allow/Block list:
- Block entries: The expiration date and notes.
- Allow entries: The expiration date and notes.
In the Microsoft 365 Defender portal at https://security.microsoft.com, go to Policies & rules > Threat Policies > Rules section > Tenant Allow/Block Lists. Or, to go directly to the Tenant Allow/Block List page, use https://security.microsoft.com/tenantAllowBlockList.
Select the URLs tab
On the URLs tab, select the check box of the entry that you want to modify, and then click the
Edit button that appears.
The following values are available in the Edit URL flyout that appears:
- Remove block entry after: You can extend block entries for a maximum of 90 days from the system date or set them to Never expire.
- Remove allow entry after: You can extend allow entries for a maximum of 30 days from the system date.
- Optional note
When you're finished, click Save.
Tip
For entries added via submission, if you select the entry by clicking anywhere in the row other than the check box, you can select View submission in the details flyout that opens up. It takes you to the submission details that added the entry.
Use PowerShell to modify existing allow or block entries for URLs in the Tenant Allow/Block List
In Exchange Online PowerShell, use the following syntax:
Set-TenantAllowBlockListItems -ListType Url <-Ids <Identity value> | -Entries <Value value>> [<-ExpirationDate Date | -NoExpiration>] [-Notes <String>]
This example changes the expiration date of the block entry for the specified URL.
Set-TenantAllowBlockListItems -ListType Url -Entries "~contoso.com" -ExpirationDate "9/1/2022"
For detailed syntax and parameter information, see Set-TenantAllowBlockListItems.
Use the Microsoft 365 Defender portal to remove existing allow or block entries for URLs from the Tenant Allow/Block List
In the Microsoft 365 Defender portal at https://security.microsoft.com, go to Policies & rules > Threat Policies > Rules section > Tenant Allow/Block Lists. Or, to go directly to the Tenant Allow/Block List page, use https://security.microsoft.com/tenantAllowBlockList.
Select the URLs tab.
On the URLs tab, do one of the following steps:
- Select the check box of the entry that you want to remove, and then click the
Delete icon that appears.
- Select the entry that you want to remove by clicking anywhere in the row other than the check box. In the details flyout that appears, click
Delete.
- Select the check box of the entry that you want to remove, and then click the
In the warning dialog that appears, click Delete.
Tip
You can select multiple entries by selecting each check box, or select all entries by selecting the check box next to the Value column header.
Use PowerShell to remove existing allow or block entries for URLs from the Tenant Allow/Block List
In Exchange Online PowerShell, use the following syntax:
Remove-TenantAllowBlockListItems -ListType Url <-Ids <Identity value> | -Entries <Value value>>
This example removes the block entry for the specified URL from the Tenant Allow/Block List.
Remove-TenantAllowBlockListItems -ListType Url -Entries "~cohovineyard.com
For detailed syntax and parameter information, see Remove-TenantAllowBlockListItems.
URL syntax for the Tenant Allow/Block List
IPv4 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
orcontoso.
are not allowed.Subpaths are not implied for allows.
For example,
contoso.com
does not includecontoso.com/a
.Wildcards (*) are allowed in the following scenarios:
A left wildcard must be followed by a period to specify a subdomain. (only applicable for blocks)
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*
orcontoso.com/ab*
are not allowed.*.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
includescontoso.com
and*.contoso.com
.
A username or password isn'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
Allow match: contoso.com
Allow not matched:
- abc-contoso.com
- contoso.com/a
- payroll.contoso.com
- test.com/contoso.com
- test.com/q=contoso.com
- www.contoso.com
- www.contoso.com/q=a@contoso.com
Block match:
- contoso.com
- contoso.com/a
- payroll.contoso.com
- test.com/contoso.com
- test.com/q=contoso.com
- www.contoso.com
- www.contoso.com/q=a@contoso.com
Block not matched: abc-contoso.com
Scenario: Left wildcard (subdomain)
Tip
Allow entries of this pattern are supported only from advanced delivery configuration.
Entry: *.contoso.com
Allow match and Block match:
- www.contoso.com
- xyz.abc.contoso.com
Allow not matched and Block not matched:
- 123contoso.com
- contoso.com
- test.com/contoso.com
- www.contoso.com/abc
Scenario: Right wildcard at top of path
Entry: contoso.com/a/*
Allow match and Block match:
- contoso.com/a/b
- contoso.com/a/b/c
- contoso.com/a/?q=joe@t.com
Allow not matched and Block not matched:
- contoso.com
- contoso.com/a
- www.contoso.com
- www.contoso.com/q=a@contoso.com
Scenario: Left tilde
Tip
Allow entries of this pattern are supported only from advanced delivery configuration.
Entry: ~contoso.com
Allow match and Block match:
- contoso.com
- www.contoso.com
- xyz.abc.contoso.com
Allow not matched and Block not matched:
- 123contoso.com
- contoso.com/abc
- www.contoso.com/abc
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
Tip
Allow entries of this pattern are supported only from advanced delivery configuration.
Entry: *.contoso.com/*
Allow match and Block match:
- abc.contoso.com/ab
- abc.xyz.contoso.com/a/b/c
- www.contoso.com/a
- www.contoso.com/b/a/c
- xyz.contoso.com/ba
Allow not matched and Block not matched: contoso.com/b
Scenario: Left and right tilde
Tip
Allow entries of this pattern are supported only from advanced delivery configuration.
Entry: ~contoso.com~
Allow match and Block match:
- contoso.com
- contoso.com/a
- www.contoso.com
- www.contoso.com/b
- xyz.abc.contoso.com
- abc.xyz.contoso.com/a/b/c
- contoso.com/b/a/c
- test.com/contoso.com
Allow not matched and Block not matched:
123contoso.com
contoso.org
test.com/q=contoso.com
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
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/*/*
Related articles
- Use the Submissions page to submit suspected spam, phish, URLs, legitimate email getting blocked, and email attachments to Microsoft
- Report false positives and false negatives
- Manage allows and blocks in the Tenant Allow/Block List
- Allow or block files in the Tenant Allow/Block List
- Allow or block emails in the Tenant Allow/Block List
Feedback
Submit and view feedback for