Applies to managed Chrome browsers and ChromeOS devices.
As an administrator, you can block and allow URLs so that users can only visit certain websites.
Filter format
The format of filters for the URLBlocklist and URLAllowlist policies is:
[scheme://][.]host[:port][/path][@query]
| Field | Details |
| scheme (optional) |
This field is optional, and must be followed by ://. For details, see Schemes you can use. Not case sensitive. |
| host (required) |
A valid hostname or an IP address. It can also take the special * value. An optional . (dot) can prefix the host field to disable subdomain matching. Not case sensitive. |
| port (optional) | Must be a valid port value from 1 to 65535. |
| path (optional) |
You can use any string here. Case sensitive. |
| query (optional) |
A set of key-value and key-only tokens delimited by &. The key-value tokens are separated by =. A query token can optionally end with * to indicate prefix match. Token order is ignored during matching. Case sensitive. |
Schemes you can use
You can use either a standard or a custom scheme. Supported standard schemes are:
- about
- blob
- content
- chrome
- cid
- data
- file
- filesystem
- gopher
- http
- https
- javascript
- mailto
- ws
- wss
All other schemes are treated as custom schemes. Custom schemes are supported, but only the patterns scheme:* and scheme://* are allowed. They match all URLs with that scheme. The scheme and the host are case insensitive, but path and query are case sensitive.
Example scheme formats
- Supported standard schemes
- http://example.com matches HTTP://Example.com, http://example.COM and http://example.com.
- http://example.com/path?query=1 doesn't match http://example.com/path?Query=1 or http://example.com/Path?query=1 but does match http://Example.com/path?query=1.
- Custom schemes
- The patterns custom://* or custom:* are valid and match custom:app.
- The patterns custom:app or custom://app are invalid.
Exceptions to URL format
The filters format is very similar to the URL format. The following exceptions apply:
- You can include user:pass fields but they will be ignored. For example, http://user:pass@example.com/pub/bigfile.iso.
- If you include a reference separator #, it is ignored along with everything that appears after it.
- The host can be *. It can also have . (dot) as a prefix.
- The host can have / or . (dot) as a suffix. If it is the case, that suffix is ignored.
Filter selection
The filter selected for a URL is the most specific match found.
Considerations
- Wildcards (*) are the last searched, and match all hosts.
- When both a block and allow filter apply at step 4 below, with the same path length and number of query tokens, the allow filter takes precedence.
- If a filter has . (dot) prefixing the host, only exact host matches are filtered. For example:
- example.com matches example.com, www.example.com and sub.www.example.com.
- .www.example.com only matches exactly www.example.com.
Filter selection process
- The filters with the longest host match are selected. Filters with a non-matching scheme or port are discarded.
- From these filters, the filters with the longest matching path are selected.
- From these filters, the filters with the longest set of query tokens are selected.
- If no valid filter is left at this stage, the host is reduced by removing the left-most subdomain, and starting again from step 1.
- If a filter is still available, the filter decision, to block or allow, is enforced. If no filter ever matches, the default is to allow the request.
URL blocklist examples
| URL blocklist entry | Result |
|---|---|
| example.com | Denies all requests to example.com, www.example.com, and sub.www.example.com. |
| http://example.com | Denies all HTTP requests to example.com and any of its subdomains, but allows HTTPS requests. |
| https://* | Denies all HTTPS requests to any domain. |
| mail.example.com | Denies requests to mail.example.com but not to www.example.com or example.com. |
| .example.com | Denies requests to example.com but not its subdomains, like example.com/docs. |
| .www.example.com | Denies requests to www.example.com but not its subdomains |
| * | Denies all requests except for those to blocklist exception URLs. This includes any URL scheme, such as http://google.com, https://gmail.com, and chrome://policy. |
| *:8080 | Denies all requests to port 8080. |
| example.com/stuff | Denies all requests to example.com/stuff and its subdomains. |
| 192.0.2.1 | Denies requests to this exact IP address. |
|
?v *?video=* *?video=100* |
Denies any request with the query ?video=100. |
| *?a=1&b=2 |
Denies any request with the following queries: ?b=2&a=1 ?a=1&b=2 ?a=1&c=3&b=2 |
| youtube.com/watch?v=xyz |
Denies youtube video with id xyz. When you block, any occurrence of the key-value pair is sufficient. When you allow, every occurrence of the key should have a matching value. Example Allowing youtube.com/watch?v=V2 does not allow youtube.com/watch?v=V1&v=V2. It does allows youtube.com/watch?v=V2&v=V2. |
Search for a match for http://mail.example.com/mail/inbox
- First find filters for mail.example.com, and go to step 2. If that fails, then try again with example.com, com, and finally "".
- Among the current filters, remove those that have a scheme that is not http.
- Among the current filters, remove those that have an exact port number and it not 80.
- Among the current filters, remove those that don't have /mail/inbox as a prefix of the path.
- Pick the filter with the longest path prefix, and apply it. If no such filter exists, go back to step 1 and try the next subdomain.
Allow only a small set of sites
- Block *.
- Allow selected sites: mail.example.com, myownpersonaldomain.com, google.com.
Block all access to a domain, except to the mail server using HTTPS and to the main page
- Block example.com.
- Allow https://mail.example.com.
- Allow .example.com, and maybe .www.example.com.
Block all access to youtube, except for selected videos.
- Block youtube.com.
- Allow youtube.com/watch?v=V1.
- Allow youtube.com/watch?v=V2.