DNS over HTTPS (DoH)
With Cloudflare Gateway, you can filter DNS over HTTPS (DoH) requests by DNS location or by user without needing to install the WARP client on your devices.
Location-based policies require that you send DNS requests to a location-specific DoH endpoint, while identity-based policies require that requests include a user-specific DoH token.
Location-based policies require that you send DNS requests to a unique DoH endpoint assigned to the location:
Obtain your location’s DoH subdomain.
Browsers can be configured to use any DNS over HTTPS (DoH) endpoint. If you choose to configure DoH directly in your browser, you must choose a Gateway DNS location as your DoH endpoint, otherwise DNS filtering will not occur in that browser.
Mozilla Firefox
- In Firefox, go to Settings.
- In Privacy & Security, go to DNS over HTTPS.
- Under Enable secure DNS using, select Max Protection.
- In Choose provider, choose Custom.
- In the field, enter
https://<YOUR_DOH_SUBDOMAIN>.cloudflare-gateway.com/dns-query
.
Firefox is now configured to use your DoH endpoint. For more information on configuring DoH settings in Firefox, refer to Mozilla’s documentation ↗.
Google Chrome
- In Chrome, go to Settings > Privacy and security > Security.
- Scroll down and turn on Use secure DNS.
- Select With Custom.
- In the Enter custom provider field, enter
https://<YOUR_DOH_SUBDOMAIN>.cloudflare-gateway.com/dns-query
.
Read more about enabling DNS over HTTPS ↗ on Chrome.
Microsoft Edge
- In Microsoft Edge, go to Settings.
- Select Privacy, Search, and Services, and scroll down to Security.
- Turn on Use secure DNS.
- Select Choose a service provider.
- In the Enter custom provider field, enter
https://<YOUR_DOH_SUBDOMAIN>.cloudflare-gateway.com/dns-query
.
Brave
- In Brave, go to Settings > Security and Privacy > Security.
- Turn on Use secure DNS.
- Select With Custom.
- In the Enter custom provider field, enter
https://<YOUR_DOH_SUBDOMAIN>.cloudflare-gateway.com/dns-query
.
Safari
Currently, Safari does not support DNS over HTTPS.
Your DNS queries will now be sent to Gateway for filtering. To filter these requests, build a DNS policy using the DNS Location selector.
Windows 11
-
Obtain the
A
andAAAA
record values associated with your location’s DoH endpoint.- Run the following command to obtain your
A
record values:
- Obtain your
AAAA
record values.
- Copy the resulting IP addresses.
- Run the following command to obtain your
-
Add the addresses to your list of known DoH servers.
- Run the following command for each address:
- Confirm the addresses were added.
-
In Windows, go to Settings > Network & internet > your active Internet connection. This option may be either Ethernet or Wi-Fi.
-
Under DNS server assignment, select Edit.
-
In the drop-down menu, choose Manual.
-
Enable IPv4.
-
In Preferred DNS and Alternate DNS, enter the IPv4 addresses from your
A
record command. Set DNS over HTTPS to On (automatic template). -
Enable IPv6.
-
In Preferred DNS and Alternate DNS, enter the IPv6 addresses from your
AAAA
record command. Set DNS over HTTPS to On (automatic template).
Windows Server 2022
Obtain the A
and AAAA
record values associated with your location’s DoH endpoint.
- Run the following command to obtain your
A
record values:
- Obtain your
AAAA
record values.
- Copy the resulting IP addresses.
- Add the addresses ↗ to your list of known DoH servers.
- Configure the Windows Server client ↗ or set up a Group Policy ↗ to use DoH.
For more information, refer to Microsoft’s DoH guide ↗ for Windows Server 2022 and newer.
In order to filter DoH queries based on user identity, each query must include a user-specific authentication token. If you have several devices per user and want to apply device-specific policies, you will need to map each device to a different email.
Currently, authentication tokens can only be generated through the API. You can run this interactive Python script which automates the setup procedure, or follow the steps described below.
Save the service token’s client_id
, client_secret
, and id
.
Example response
If you get an access.api.error.service_token_not_found
error, check that {service_token_id}
is the value of id
and not client_id
.
Example response
Create a new user and optionally add them to a group.
Save the user’s id
returned in the response.
Example response
Request a DoH token for the user, using your service token to authenticate into your team domain.
The response contains a unique DoH token associated with the user. This token expires in 24 hours. We recommend setting up a refresh flow for the DoH token instead of generating a new one for every DoH query.
Example response
Send DoH queries to the resolver at https://<ACCOUNT_ID>.cloudflare-gateway.com/dns-query
, making sure to include the user’s DoH token in the CF-Authorization
header.
If the site is blocked and you have enabled Display block page for the policy, the query will return 162.159.36.12
(the IP address of the Gateway block page). If the block page is disabled, the response will be 0.0.0.0
.
Example response
You can verify that the request was associated with the correct user email by checking your Gateway DNS logs. To filter these requests, build a DNS policy using any of the Gateway identity-based selectors.