Guides
ProductDeveloperPartnerPersonal

Connect Active Directory to Umbrella to Provision Users and Groups

You must connect your Active Directory (AD) to Umbrella in order to provision users and groups from Active Directory.

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.

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.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 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 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 OpenDNSConnector. A custom username can also be used but must be configured with the required permissions as listed below.
    Note: Add the custom username at the end of the configuration script command. For example,
    **cscript <_filename
    > --username <sAMAccountName for custom user>** .
    Substitute the Windows configuration script filename (including the wsf file extension) for <filename> in the cscript command.
  • '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. Alternatively, 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 communicates 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 the 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 users and groups. 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 users and groups 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 the retrieval of users and groups.

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.

Note: If you have deployed any virtual appliances, you need to register all of your domain controllers that are handling Active Directory authentication. Otherwise, not all users and groups in the Active Directory will be identified.

Register a Domain Controller

  1. Navigate to  Deployments > Configuration > Sites and Active Directory and click Add.
1324
  1. Select Domain Controller and then click Next.
1000
  1. Confirm that you have provided permissions for the Connector account as specified in Prerequisites and click Next.
    Note: See Run the Configuration Script on the Domain Controllers to download the configuration script.
1008
  1. Enter the hostname, internal IP address, and the domain of the DC. Choose 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.
1324
  1. Select Domain and then click Next.
999
  1. Add the Domain, choose an appropriate Umbrella site from the Site drop-down list, and then click Save.
1000

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.
    Note: If Selective Sync is enabled, AD Users and Computers that are not members of Groups specified in CiscoUmbrellaADGroups.dat or their sub-groups will 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, log into 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. We do not recommend that you install the connector from a network drive or run 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.
    Note: 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. 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 Umbrella

  1. Once the connector is installed, return to the Umbrella dashboard and navigate to Deployments > Configuration > Sites and Active Directory.
1324
  1. The hostname of the Windows machine where you installed the connector is listed.
    The status of your domain controller and connectors 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.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.
  2. 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 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).


Connect Multiple Active Directory Domains to Umbrella < Connect Active Directory to Umbrella to Provision Users and Groups > Change the Connector Account Password