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    

Connect Active Directory to Umbrella

Table of Contents

Register a Domain Controller or Domain in the Umbrella Dashboard

Active Directory integration requires you to register an AD domain controller or AD domain in the Umbrella dashboard. The Connector will perform an LDAP sync against this domain controller or domain to retrieve the user and group identities. The Connector Server must be able to communicate with the domain controller over port 389/636 TCP for LDAP sync or LDAP over SSL.

The Connector can only retrieve user and group identities from a single domain controller. If you register multiple domain controllers on the Umbrella dashboard, the Connector will only attempt to perform an LDAP sync against the first domain controller in the list. Ensure that the domain controller you are registering is not subject to any AD replication delays. Read-only Domain Controller (RODC) registrations are supported for retrieval of user and group identities.

If you need to periodically bring down your domain controller for maintenance or updates or your domain controllers are behind a load balancer that does not support LDAP queries, it is recommended to register the domain instead.

Register a Domain Controller

  1. Navigate to Deployments > Configuration > Sites and Active Directory and click Add.
  2. Select Domain Controller and click Next.
  1. Confirm that you have provided permissions for the Connector account as specified in the Prerequisites section and click Next.
  1. Enter the Hostname, Internal IP address, and the Domain of the DC. Select the appropriate Umbrella Site for the Domain Controller and click  Save.

Register a Domain

  1. Navigate to Deployments > Configuration > Sites and Active Directory  and click Add.
  2. Select Domain and click Next.
  1. Enter the Domain, select the appropriate Umbrella Site for the domain and click  Save.

Specify AD Groups of Interest (Optional)

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.
    Note: 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.

  2. 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.

  3. List the AD groups that need to be synchronized in distinguished name (DN) format in this file.

Supported OUs

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
  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

  1. On the server that you have configured to deploy the connector, login to the Umbrella dashboard, navigate to  Deployments > Configuration > Sites and Active Directory and click Download.
  2. Click Download for Windows Service (Active Directory Connector).
    Note: 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 the prompts in the setup wizard and click Close when finished.
  5. Return to the Umbrella dashboard. Verify that the connector is in the same Umbrella site as the domain controller or domain that it needs to communicate with.

Verify That the Connector Syncs with the Umbrella Dashboard

  1. Once the connector is installed, return to the Umbrella dashboard and navigate to Deployments > Configuration > Sites and Active Directory.
  2. The hostname of the Windows machine that you installed the connector is listed.
    The status of your domain controller and connector(s) should change from Inactive to Active within some time. If not, contact Umbrella Support.
    Note: If the connector does not appear in the dashboard and port 443 is confirmed to be open to,, and, the connector server may be missing the DigiCert CA. To confirm, visit 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 Umbrella Support.
  3. Navigate to Deployments > Core Identities > Users and Groups, expand the Active Directory section, and click View AD Users and Groups. Confirm that groups and users are added.

Seeing your groups listed means the domain controllers have automatically synchronized 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 Sites and Active Directory page to see if the status of all components is Active (green). If not, contact umb[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).

Prerequisites < Connect Active Directory to Umbrella > Connect Multiple Active Directory Domains to Umbrella

Updated about 12 hours ago

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.