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    

2. Connect Active Directory to Umbrella

The purpose of the connector is to monitor one or more domain controllers. It listens to user and computer logins through the security event logs and subsequently enables IP-to-user and IP-to-computer mappings on the virtual appliances (VAs). It synchronizes user-to-group, computer-to-group and group-to-group memberships with the Umbrella Security Cloud, enabling you to create and enforce group-based settings and view user, computer, and group-based reports.

Deployments without the virtual appliance

If you are using the Umbrella roaming client alone, you must enable Active Directory identity support. For more information, see Identity Support for the Roaming Client.

The connector helps import your Active Directory (AD) users, groups, and computers to provide these mappings. Other AD objects, including Organization Units (OUs), are not imported.

  1. Specify AD groups to be imported to Umbrella (optional).
  2. Install the Connector.
  3. Verify that the connector syncs with the Umbrella dashboard.
  4. Verify that all AD components are operational.

Note: Only one connector is required per Umbrella site, with an optional second connector for redundancy if required. If you are onboarding multiple AD domains, one connector is required per AD domain per Umbrella site, with an optional second connector for redundancy if required. We do not recommend installing the connector on all domain controllers.

The connector service does not have to be installed on a domain controller. It can be installed on any Windows server that is a member of the domain.

Specify AD Groups of Interest

Optionally, you can specify AD Groups of interest for the purpose of policy creation in Umbrella.

  1. Identify the AD groups of interest. Users and computers belonging to these groups will be synchronized to Umbrella.

For each sub-tree, only the parent group needs to be specified. All AD groups, users, and computers that are part of this parent group will automatically be included.

Using Selective Sync

If Selective Sync is enabled, AD Users and Computers that are not members of Groups specified in CiscoUmbrellaADGroups.dat or their sub-groups not be synchronized to Umbrella and will be completely exempt from Umbrella Policies and Reporting.

  1. Create a CiscoUmbrellaADGroups.dat file in the C:\ drive of each machine where the connector will be installed.
    The connector will only read the C:\CiscoUmbrellaADGroups.dat file. If the file is incorrectly named or is not present in the C:\ drive, all groups will be imported to Umbrella.
  2. List the AD groups that need to be synchronized in distinguished name (DN) format in this file.

Caution: AD Groups only

Not Supported: OU=My OU,OU=Organizational Unit,DC=sample,DC=local
Supported: CN=My Group,OU=Organizational Unit,DC=sample,DC=local

Sample file entries:

  • CN=Engineering,CN=Builtin,DC=ciscoumbrella,DC=com
  • CN=Sales,CN=Builtin,DC=ciscoumbrella,DC=com
  • CN=Marketing,CN=Builtin,DC=ciscoumbrella,DC=com
Get-ADGroup -Identity <ADGroupName> 
  1. Ensure that there are no blank lines anywhere in the file.
    Note: If you are running multiple connectors, the file C:\CiscoUmbrellaADGroups.dat should be present on each system running the connector and should be identical on each system.

Total Number of Groups Selected for Synchronization

The total number of groups selected for synchronization—groups specified in the selective sync file and all their sub-groups—should not exceed 15,000. Also, these groups should not be nested within more than five OU levels. Selective synchronization fails in both cases. If either of these requirements cannot be met, the selective sync file should not be used so that a full AD tree synchronization can be done instead.

Install the Connector

The connector service does not have to be installed on a domain controller. It can be installed on any Windows server that is a member of the domain, provided that the following requirements are met:

• Windows Server 2012, 2012 R2, 2016 or 2019 with the latest service packs and 100MB free hard disk drive space.
Service packs prior to SP2 are not supported.
• .NET Framework 4.5 or 4.7.
.NET Framework 3.5 should not be running on the same system. If .NET Framework 3.5 is required, make sure that all Windows patches on this server are applied.

  • If a local anti-virus application is running, allow list the OpenDNSAuditClient.exe and OpenDNSAuditService.exe processes.
    • AD Domain Services Snap-ins and Command-line Tools feature installed through Remote Server Administration Tools > Role Administration Tools > AD DS & AD LDS Tools > AD DS Tools.
  1. Navigate to Deployments > Configuration > Sites and Active Directory and click Download.
  1. Click Download for Windows Service (Active Directory Connector).


You must download the ZIP file to the local machine where you plan to run it or copy it locally from another machine. Issues have been observed attempting to install the connector from networked drives as well as running the setup.msi directly from the compressed file.

  1. As an admin, extract the contents of the ZIP file you downloaded to a folder and then navigate to that folder.
  2. Run setup.msi.
  3. Enter the username of the Connector user (OpenDNS_Connector or custom username) and the password. See Prerequisites.
  4. Follow prompts in the setup wizard and click Close when finished.
  5. Return to the Umbrella dashboard. If you have configured multiple Umbrella sites, confirm that your Connector is in the same Umbrella site as the Domain Controllers and VAs it needs to communicate with. Verify that the connector syncs with the Umbrella dashboard.

Verify That the Connector Syncs with the Umbrella Dashboard


If the connector does not appear in the dashboard 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 Global Root CA from DigiCert and restart the Connector service. If it does not appear, contact support.

  1. Once the connector is installed, return to the Umbrella dashboard and navigate to Deployments > Configuration > Sites and Active Directory.
    On the Sites and Active Directory page, the hostname of the domain controller or other Windows machine that you installed the connector is listed.
    The Umbrella Security Cloud automatically configures and connects the VAs to the domain controllers through the connectors for each configured site. The status of all of your VAs, AD servers, and connectors should change from Inactive to Active. If not, contact support.
  2. Navigate to Policies > Management > All Policies and click Add.
  3. Confirm that groups are added:
    a. Navigate to the What would you like to protect? page of the Policy wizard and under Select Identities, click AD Groups to expand it.
    You should see your groups listed.

Seeing your groups listed means the domain controllers or other Windows machine have automatically synchronize user and computer group memberships with Umbrella through the connector successfully. Any subsequent changes should also sync successfully.

If you don’t see your groups, check the Active Directory Configuration page to see if the status of all components is Active (green). If not, contact [email protected].

Note: It can take up to four hours for large numbers of AD user, computer and group objects to synchronize for the first time. During this time, the connector status icon may appear as red until the initial sync is complete. After the sync completes, it will be labeled as "Active" (green).

For information about configuring a policy, see 3. Configure Policies.

Verify That all Active Directory Components are Operational

  1. If your deployment includes VAs, confirm that you can resolve DNS traffic by entering the following command that sends a query to through your VA.
> server {enter the IP of one of your VA's}  
  1. You can further verify DNS traffic by entering the following command to send a TXT Record query to through the VA.
> set type=TXT  
> exit

This query returns a string of information if you are going through the VA. If you receive a non-existent domain result from that query, there is still something wrong with your configuration and you should contact support.

1. Prepare Your Active Directory Environment < 2. Connect Active Directory to Umbrella > 3. Configure Policies

Updated 7 months ago

2. Connect Active Directory to Umbrella

Suggested Edits are limited on API Reference Pages

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