Guides
ProductDeveloperPartnerPersonal

Connect Active Directory to Umbrella VAs

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

Prerequisites

Connector Server

You must configure a server that is a member of the AD domain with the following environment:

  • Windows Server 2012, 2012 R2, 2016, 2019 or 2022 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 above
  • 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. This is required for troubleshooting purposes

If you are deploying AD integration with Virtual Appliances through integration with domain controllers, you will need to deploy one connector per AD domain (with an optional second connector per AD domain for redundancy).

If you have already deployed a centralized Windows Event Log Collector to which all domain controllers forward login events, and you wish to deploy AD integration with Virtual Appliances using this Windows Event Log Collector, you will need to deploy a single AD connector for all AD domains, with an optional second connector for redundancy.

Outbound Network Access to Cisco Umbrella

The Connector server requires outbound access as specified below:

  • 443 (TCP) to api.opendns.com for syncing
  • Access to additional URLs on port 80/443 (TCP) may be required for Windows to perform Certificate Revocation List and Code-Signing checks. For a complete list of ports, see the section on Communication Flow and Troubleshooting.
  • 443 (TCP) to disthost.umbrella.com (for downloading upgrades)

If you are using a transparent HTTP web proxy, ensure that the URLs on port 80/443 are excluded from the proxy, and not subject to authentication.

Connector Account

The connector deployment requires you to create a new user account in each AD domain that needs to be integrated. This account should have:

  • The logon name (sAMAccountName) set to OpenDNS_Connector. A custom username can be configured, but this custom username should be specified as a parameter when running the Configuration Script on the Domain Controller.
  • Password never expires selected
    Note: Passwords must not include backslashes, quotations (single or double), greater-than or less-than chevron brackets (< >), or colons.
  • The Connector account (OpenDNS_Connector or custom username) must be a member of the following built-in groups on each AD domain:
  • Enterprise Read-only Domain Controllers
  • Event Log Readers

Note: In a parent/child domain scenario, the "Enterprise Read-only Domain Controller" only exists in the parent domain. In this case, follow the instructions listed here to provide the required permissions for the Connector account. You must add other missing groups.

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 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.
    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.
1324
  1. 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.
868
  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. 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 or 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. 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.
1324

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.

  1. Navigate to Deployments > Core Identities > Users and Groups. 
1201
  1. Click to expand the Active Directory section and click View AD Users and Groups. Confirm that your groups and users are added.  
    If your groups are listed, 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 users, computers, 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 VAs > Multiple Active Directory and Umbrella Sites