In this article

This article provides steps to deploy the DNSFilter Chrome Roaming Client Extension version 3.x.x. This Extension version supports Google's Manifest 3 and validates DNS over HTTPS (DoH) on managed Chromebooks.

Limitations

• The DNSFilter Chrome Extension can only be deployed with Chromebook-compatible Mobile Device Management (MDM) tools 
  • Unmanaged devices cannot sync with the DNSFilter app in order to apply filtering policies
• The Chrome extension is tested with G Suite deployments but can be deployed with other MDM platforms. Check your MDM's support documentation for capabilities and limitations
• Configuring local domains is available via the Google Admin dashboard

Step one: Set the Device Network Hostname

Setting the Device Network Hostname Template prevents devices from appearing as “[blank]” in DNSFilter dashboard, ensuring the correct device name and client registration are properly displayed.

Step two: Install the Chrome Extension

These steps use the Google Admin dashboard, but other MDM's use a similar extension setup.

Add the Organization Unit (OU)

1. Login to the Google Admin dashboard and navigate to Devices
   1. Select Chrome
   2. Select Apps & Extensions
   3. Select Users & browsers
   4. Select the Organizational Unit of users
2. Select Add (➕)
3. Select Add Chrome Extension by ID
   
   
4. Select From Custom URL
5. Enter this Extension ID and Custom URL:

   Extension ID: ahailcbfmbjeilfjapehbjlclkeffojh
   Custom URL: https://chromeupdate.dnsfilter.com/chrome-extension/updates.xml

6. Select Save to add the OU

Install the Policy

1. From the DNSFilter Roaming Clients dashboard, copy the Extension Policy:
   1. Select Install Roaming Client
   2. Select the associated Site
   3. Select ChromeOS
   4. Copy the Policy for Extension
      
      
2. Navigate back to Google Admin and select Installation Policy
3. Set it to Force Install + pin to browser toolbar
   
   
4. Paste the policy in the Policy for extensions field
5. Toggle on Update URL to Installation URL(see above) to help configure future updates
6. Select Save

The Chrome Extension is now installed. Continue to step three to configure DoH settings.

Step three: Configure DoH settings

1. From the DNSFilter Roaming Clients dashboard, copy the DNS over HTTPS Template:
   1. Select Install Roaming Client
   2. Select the associated Site
   3. Select ChromeOS
   4. Copy the DNS over HTTPS Template
      
      
2. Navigate to the Google Admin dashboard and select Devices
   1. Select Chrome
   2. Select Settings
   3. Select the OU of users
   4. Select Users & browsers
   5. Search the term DNS over HTTPS or DoH
3. Select DNS-over-HTTPS 
   
   1. Set DNS over HTTPS mode to Prefer DNS Over HTTPS, allow insecure fallback
   2. Select Save
      
      
4. Navigate back to the search results
5. Select DNS-over-HTTPS templates with identifiers
6. Configure the template
   1. Select Configuration
   2. Paste the template copied from the DNSFilter dashboard under DNS over HTTPS templates
   3. Select Save
      
      

DoH settings are now configured. Continue to step four to deploy the CA Root certificate.

Step four: Upload the CA Root Certificate

🚨 Failure to upload the CA Root Certificate will result in generic error messaging instead of a Block Page when end-users navigate to blocked websites. 

1. From the DNSFilter Tools SSL Certificate dashboard, download the certificate. Select any OS for the download; the certificate is the same across OS platforms
   ✍️ For distributors managing both branded and unbranded environments, make sure to align the certificate appropriately to avoid misconfigurations between Whitelabeled extensions and branded certificates (or vice versa).
2. Navigate to the Google Admin dashboard and select Devices
3. Select Networks
4. Select the OU of users
5. Select Add Certificate
   1. Upload the certificate
   2. Check Enabled for Chromebook
6. Select Save
   
   

The CA Root Certificate is now uploaded. Users will see the block page if they navigate to blocked websites.

Configure Local Domains to resolve without DoH (optional)

Local domains to bypass DNSFilter are managed in the Google Admin dashboard for the Chrome Extension. 

1. Navigate to the Google Admin dashboard and select Chrome browser
   1. Select Settings
   2. Select User & browser settings
2. Select DNS over HTTPS included and excluded domains
3. Add the excluded domains. Traffic to these domains will not be filtered by DNSFilter policies
4. Select Save
   
   

The Chromebook will use the original system DNS to resolve queries to these domains.

Having issues? See the Chrome Extension Troubleshooting article to address common blocks.