The Umbrella Documentation Hub

Welcome to the Umbrella documentation hub. Here you'll find access to all of our Cisco Umbrella user guides.

Get Started    

1. Prepare Your Active Directory Environment

If you are performing an Active Directory (AD) integration, it can be done either by having virtual appliances (VAs) deployed or roaming clients installed. The script below is required for both integrations, but we recommend having a VA or at least one roaming client configured before proceeding with these steps.

If your deployment includes VAs, run the Windows Configuration script on all of the domain controllers at each site, excluding read-only domain controllers (RODCs) on each domain that needs to be integrated with Umbrella. This script prepares them to communicate with the connector.

If your deployment only includes roaming clients, run the Windows Configuration script on a single domain controller for each AD domain that you want to integrate with Umbrella. This script prepares it to communicate with the connector.

For information on changes made by the script, see Required Permissions for the OpenDNS_Connector User.

Read Only Domain Controllers

RODCs are not supported for VA deployments. RODCs are supported for Roaming Client only deployments, provided the RODC is running a Global Catalog (GC) server.

Roaming Client-only Deployments

The AD Connector communicates with only a single Domain Controller for Roaming Client-only deployments. If your deployment does not include VAs and you have previously registered multiple Domain Controllers (AD Servers), some of them will appear in an Error state on the Umbrella dashboard because the Connector does not communicate with them. This will not impact the functioning of the Connector. It is safe to delete all except one of these Domain Controllers from the dashboard.

Run the Configuration Script on the Domain Controllers

  1. Navigate to Deployments > Configuration > Sites and Active Directory and click Download.
  1. Click Download for Windows Configuration Script for Domain Controller.
  1. Download and save the Windows Configuration Script file to a location on the machine where you plan to run it.Note: The configuration script is written in Visual Basic Script and is human readable. For reference, it automates the instructions you’ll find in Appendix B – Multiple Active Directory and Umbrella Sites, plus more. For more information, contact [email protected].
  2. As an administrator, open an elevated command prompt.

Before Proceeding

The Connector user must be created before running the script, as detailed in the prerequisites. There are also several Group Policies that affect system operation that may need manual configuration. The script displays the status of these settings and, if needed, provides instructions on how to change them.

  1. If your deployment includes VAs, from the command prompt, enter: cscript <filename>
    Where <filename> is the name of the configuration script you downloaded in Step 2.
    If your deployment does not include VAs, from the command prompt, enter: cscript <filename> --forcenonva true
    Using this parameter ensures that your connector will not subscribe to WMI events from the domain controller.
    If you are using a custom username for the Connector account, use the command cscript <filename> --username <sAMAccountName for custom user>, or cscript <filename> --username <sAMAccountName for custom user> --forcenonva true depending on whether your deployment includes Virtual Appliances or not.
    If you do not specify any custom username, the script assumes the Connector account name to be OpenDNS_Connector.
    The script displays your current configuration, then offers to auto-configure the domain controller for operation. If the auto-configure steps are successful, the script offers to registers the domain controller with the Umbrella dashboard. Registration only occurs if you accept this offer.


If you receive the error message "Please verify that the Domain Controller can access the Umbrella API(, at port 443!" and port 443 is confirmed to be open to,, and, the domain controller may be missing the DigiCert CA. To confirm, visit and if a certificate error is presented, download and install the latest DigiCert CA from DigiCert and re-run the configuration script.

Verify the Active Directory Server Reports to the Dashboard

When you return to the Umbrella dashboard, you will see the hostname of the AD server you just ran the script on in the Inactive state on the Active Directory Configuration page. If you have configured multiple Umbrella sites and have deployed Virtual Appliances, make sure that the AD server is in the same Umbrella site as the Virtual Appliances that will receive DNS queries from the users in that AD domain.


The configuration script only runs once; it is not an application or service. If you change the IP address or hostname of the domain controller, remove the previous instance of the domain controller: click the round X icon to delete it from the Umbrella dashboard. Then, repeat step 1 through 5 to re-register the domain controller.

If your deployment includes VAs, repeat the above steps to prepare additional domain controllers in each AD domain environment to successfully communicate with the connector. For VA deployments, it's essential that each domain controller in each AD Domain domain environment has the configuration script run on it in order for the service to work as expected, both for high availability and overall reliability.

Prerequisites < 1. Prepare Your Active Directory Environment > 2. Connect Active Directory to Umbrella

Updated 2 months ago

1. Prepare Your Active Directory Environment

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.