Guides
ProductDeveloper
Guides
ProductDeveloper

Connect Active Directory to Umbrella to Provision User and Groups

You must connect your Active Directory (AD) to Umbrella in order to provision user and group identities from Active Directory.

Table of Contents

Prerequisites

Connector Server

To support Umbrella Active Directory (AD) integration, 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.

The Connector may be deployed directly on the Domain controller. In this case, the domain controller must meet all prerequisites listed above. Only one connector is required to provision identities from an AD domain, with an optional second connector for redundancy if required.

Outbound Network Access to Cisco Umbrella

The Connector server requires the following outbound access:

  • 443 (TCP) to api.umbrellagov.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  Communication Flow and Troubleshooting.
  • 443 (TCP) to disthost.umbrellagov.com (for downloading upgrades)

If you are using a transparent HTTP web proxy, ensure that the above 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 the AD domain. This account should have:

  • The logon name (sAMAccountName) set to OpenDNS_Connector. A custom username can also be used but must be configured with the required permissions as listed below.
  • 'Password never expires'  selected
    Note: Passwords must not include backslashes, quotations (single or double), greater-than or less-than chevron brackets (< >), or colons.
  • ‘Read’ and ‘Replicating Directory Changes’ permission assigned. Alternately, you can make the connector account a member of the built-in ‘Enterprise Read-only Domain Controllers’ group which will automatically assign these permissions.
    Note: The Connector does an initial synchronization of the AD structure to Umbrella. After this, it detects changes to the AD structure and communicate these changes only. The detection of changes requires the ‘Replicating Directory Changes’ permission, so the Connector cannot function without this permission. The ‘Replicating Directory Changes’ permission is different from the ‘Replicating Directory Changes All’ permission which enables retrieval of password hashes. The Connector does not read password hashes and hence does not require the ‘Replicating Directory Changes All’ permission.

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.
1324
  1. Select Domain Controller and click Next.
1000
  1. Confirm that you have provided permissions for the Connector account as specified in Prerequisites and click Next.
1008
  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.
    The Active Directory connector within the chosen Umbrella site will attempt to connect to your newly added domain controller. If all the required permissions have been configured, you should not experience any issues. If there are errors, review Prerequisites or contact Support.
1010

Register a Domain

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

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.
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. 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 api.umbrellagov.com, crl4.digicert.com, and ocsp.digicert.com, the connector server may be missing the DigiCert CA. To confirm, visit https://api.umbrellagov.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.
  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 [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 2 months ago