DNS-over-HTTPS (DoH)

Mobile Devices

At this time, DoH capabilities are only available on macOS, Windows, and Linux Client platforms.

DNS-over-HTTPS (DoH)

Twingate provides native DNS-over-HTTPS (DoH) capabilities for every user in your Twingate network running macOS, Windows, or Linux Client.

Because Twingate operates at the network level on a user’s device, Twingate DoH will encrypt all DNS traffic regardless of the originating application with no configuration changes required other than running the Twingate Client. You can access DoH configuration settings from the Secure DNS page under the Internet Security tab in the Admin Console.

The following options are available:

• Toggle whether DoH is enabled for your entire account.
  DoH is disabled by default.
• Set the DoH resolver.
  We offer a number of pre-configured public resolvers as options, and you may also use a custom DoH resolver.
• Determine the resolver fallback behavior.
  You may either enforce strict usage of the DoH resolver, including when it is unavailable, or allow fallback to regular DNS if name resolution fails, or the DoH resolver is unavailable.
• Set exceptions for groups that should not have DoH enabled.
  Any number of exception groups may be chosen.

How does DoH behave when enabled?

When DoH is enabled, the client will behave in the following way:

1. Any time a user is logged into the client, the client will receive a DoH configuration from the server.

• If DoH is enabled for your account, and the user is not a member of a DoH exception group, the client will enable DoH.
• Otherwise, DoH will be disabled.

2. Once the client receives its configuration and enables DoH, any DNS A queries on the user’s device that are not destined for a Twingate Resource will be encapsulated in a DoH request and sent to the configured DoH resolver.

• Note that AAAA (IPv6) queries are not supported at this time, and local resolution will fallback to IPv4 before being encapsulated in a DoH request.

3. Depending on the configured fallback method, the following behavior applies:

• Strict mode will never fall back to regular DNS requests. If the DoH resolver is not available, all DNS requests will fail. This also means that private DNS requests, which cannot be resolved by the configured DoH resolver, may also fail.
• Automatic mode will fall back to regular DNS requests if either the DoH resolver is unavailable or name lookup fails at the configured DoH resolver.

If the Twingate Client is configured to start at login, DoH protection will be enabled as soon as the Twingate Client application starts after machine boot.

DoH Resolver Configuration

You can select from a number of trusted public DoH resolvers when configuring DoH.

You may also choose a custom resolver if you prefer to use a different public DoH resolver, or if your organization uses a private DoH resolver configuration. This option is most common when using a DNS filtering service that you wish to enable for users via Twingate.

When setting a custom DoH resolver, we do not check if the address is a valid DoH resolver beyond being an HTTPS endpoint. Misconfiguring the URL can hence result in DNS queries failing for all users if DoH is also set to Strict mode.

Custom DoH Resolver Template Fields

When using a custom DoH resolver, you may want to pass device-specific information to the DoH resolver. Twingate supports several fields that can be added to a URL:

• ${deviceName}: the device’s title and friendly Twingate name, e.g. “Alex’s MacBook Pro”.
• ${deviceId}: the device’s Twingate ID.
• ${deviceModel}: the device’s model, e.g. “MacBook Pro (16-inch, M1 Pro, Late 2021)”.
• ${deviceHostname}: the device’s hostname, e.g. “alexs-macbook-pro.local”.
• ${userEmail}: the device owner’s email.

When a device queries your DoH resolver, these templates will be replaced by the device’s information. For example,

https://doh.example/query?deviceHostname=${deviceHostname}

would be formatted as

https://doh.example/query?deviceHostname=alexs-macbook-pro.local

using the device information from above.

DoH as a Resource

Client Versions

DoH as a Resource requires a Client with one of these versions or newer:

• macOS 2024.311
• Windows 2024.351
• Linux 2024.331

When the DoH resolver’s domain name matches one of your Resources, DoH will be resolved through that Resource. For example, if your DoH resolver is set to https://doh.autoco.internal/dns-query and you have a matching Resource with the address doh.autoco.internal, DoH traffic will be sent to that Resource.

Wildcards like *.autoco.internal are supported, and DoH will be routed through a matching wildcard Resource if one exists.

DoH Resources must have a Device-only Resource Policy. If the DoH Resource does not have a device-only policy, end users will not have functioning DNS as they will be unable to authenticate.

Fallback Methods

The Fallback Method determines the behavior when either the DoH resolver itself is unavailable, or an address cannot be resolved by the DoH resolver. For example, private DNS address resolution is not possible from a public DoH resolver.

• When set to Strict, the Client will never fall back to regular DNS requests, even if the DoH resolver is not available.
• When set to Automatic, the Client will fall back to regular DNS requests when either the DoH resolver is not available or an address lookup fails.

The default fallback method is Automatic.

Exception Groups

Exceptions to DoH configuration may be also be set. Any groups added to the exception list will not receive a DoH configuration and the Twingate Client will use public DNS as configured on the user’s device. If a user belongs to at least one group that is part of the exception list, their Twingate Client will use public DNS as configured on their device.

Last updated 5 months ago