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

To prepare for an Active Directory (AD) integration, we recommend that you deploy a virtual appliance or install at least one roaming client before proceeding with the configuration steps. You can set up both types of integration with the Windows configuration script.

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. The configuration script prepares the domain controllers 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. The configuration script prepares the domain controller 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

Read-only domain controller (RODC) registrations are supported only for AD Integration directory sync with Umbrella roaming client deployments. Registering a read-only domain controller in an organization in which virtual appliances are unsupported may result in an error. To deploy a read-only domain controller, add your read-only domain controller from the dashboard or run the configuration script with the option "--forcenonva true".

Roaming Client-only Deployments

The Active Directory Connector only communicates with a single domain controller for roaming client deployments. If your deployment does not include VAs and you have previously registered multiple domain controllers (AD Servers), some of the domain controllers may appear in an Error state on the Umbrella dashboard. The Error state represents a communication failure between the domain controller and the connector. This error does 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, the configuration script automates the instructions found in Appendix B – Multiple Active Directory and Umbrella Sites. For more information about the Windows configuration script, contact [email protected].

  1. As an administrator, open an elevated command prompt.

Before Proceeding

The Connector user must be created before running the script. For more information, see Active Directory Prerequisites. There are several Group Policies that may need manual configuration. The script displays the status of these settings and, if needed, provides instructions on how to change them.

  1. Locate the Windows Configuration Script file and run the script in the command prompt.

Note: Substitute the Windows configuration script filename (including the wsf file extension) for <filename> in the cscript command.

  • If your deployment includes VAs, use the command: cscript <*filename*>
  • If your deployment does not include VAs, use the command: cscript <*filename*> --forcenonva true
    The forcenonva parameter ensures that your connector does 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, if your deployment includes virtual appliances, use the command: cscript <*filename*> --username <sAMAccountName for custom user> --forcenonva true
    If you do not specify a 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.

Add Service Account Exceptions

If your deployment includes Virtual Appliances, navigate to the Deployments > Service Account Exceptions page and enter all service accounts here. This is required to prevent user activity from getting attributed to service accounts. For more information see Active Directory User Exceptions (for Active Directory Integrations).

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

Updated about a month 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.