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

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 transmits IP-to-user and IP-to-computer mappings to 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.

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.

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 through domain controller integrations, one connector is required per AD domain per Umbrella site, with an optional second connector for redundancy if required.

Table of Contents

Specify AD Groups of Interest

You can optionally specify AD Groups of interest for the purpose of policy creation in Umbrella. This is to avoid synchronizing all your AD groups to Umbrella and is recommended for easier policy management.

  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 only reads 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.
    Get-ADGroup -Identity <ADGroupName>

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

The connector can be installed on a domain controller or a server that is a member of the domain that meets the pre-requisites as specified in Prerequisites. Also verify that network connectivity requirements specified in Communication Flow and Troubleshooting are met.

  1. In 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. We do not recommend that you install the connector from a network drive or run 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. If you run the AD Connector installer files from the root directory of your device, you may encounter installation errors.
  2. Run setup.msi.
  3. Enter the username of the Connector user (OpenDNS_Connector or custom username) and the password. For more information see Prerequisites.
  4. Follow the prompts in the setup wizard and click Close when finished.
  5. Return to the Umbrella dashboard. If you have configured multiple Umbrella sites, make sure that your Connector is in the same Umbrella site as the VAs and Domain Controllers/Event Log Collector 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 api.opendns.com, crl4.digicert.com, and ocsp.digicert.com, the connector server may be missing the DigiCert CA. To confirm, visit https://api.opendns.com/v2/OnPrem.Asset 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 Umbrella 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 connector server 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 Umbrella Support.
  2. Navigate to Deployments > Core Identities > Users and Groups. 
  3. Click to expand the Active Directory section and click View AD Users and Groups. Confirm that groups and users are added.  
    If your groups are 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 [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).

Prepare Your Active Directory Environment < Connect Active Directory to Umbrella > Multiple Active Directory and Umbrella Sites

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