(Draft) Connect Active Directory to Umbrella for Roaming Clients

The purpose of the Umbrella Active Directory (AD) connector with the roaming client is to build an AD user mapping for the Umbrella roaming client's identity support feature. You can then use the Umbrella dashboard to apply policy and report AD users in reports.

The connector synchronizes user-to-group and group-to-group memberships with the Umbrella cloud, enabling you to create and enforce group-based settings and view user reports.

The AD Connector is used to upload the AD directory structure, and sync on any change to the structure. Other AD objects, including Organization Units (OUs), are not imported.

Virtual appliances (VAs) are not required for roaming client AD integrations.

In order to sync the AD tree for use with the roaming client's AD integration, you must have at least one Umbrella AD Connector service installed and running to perform the sync. If the connector is uninstalled, any new AD changes will not be reflected; however, any AD users and groups already synced to the dashboard will continue to apply.

Note: Only one connector is required, but you can install an optional second connector for redundancy if required. Although you can install as many connectors as you'd like, only one connector will actually do the syncing and the second (or third) is there for redundancy in case the first one (or the server it's installed on) goes down.

The connector service does not need to be installed on a domain controller. It can be installed on any Windows server that is a member of the domain, provided the requirements mentioned here are met: Appendix C – Prepare A Separate Non-AD Server To Install The Connector.

Prerequisites

See Prerequisites.

Active Directory Environment

• Windows Server 2012 and 2012 R2, 2016, or 2019 with the latest service packs and 100MB free hard disk drive space.
• .NET Framework 4.5 or 4.7.
  .NET Framework 3.5 should not be running on the same system. If .NET Framework 3.5 is required, confirm that all Windows patches on this server are applied.
• If a local anti-virus application is running, allow list the OpenDNSAuditClient.exe and OpenDNSAuditService.exe processes.

🚧

Important

Windows Server 2003 is not an officially supported operating system.** This documentation does outline how to install the AD Integration with 2003, but this is provided for reference only. While production deployments using Windows Server 2003 may work, they are not encouraged.

Umbrella API Access

All Umbrella Active Directory components (specifically connectors and domain controllers) require access to the Umbrella API. The domain controllers require access only while the one-time script is running. The following network requirements must be in place:

• 443 (TCP) to api.opendns.com
• 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 Appendix A – Communication Flow And Troubleshooting.

Domain Controllers and the Domain Controller script

One DC in the domain needs to perform a one-time registration with the Cisco Umbrella API. Our registration script needs to be run on one DC in the domain to register with the Umbrella API. This can be found at Deployments > Configuration > Sites and Active Directory.

Connector Server

A connector must be installed on one DC in the domain. Its location is not important. This allows for the mapping between the DCs and the API.
LDAP Sync: the connector server will talk to all domain controllers that are located in the same site. This is not required for roaming client AD integration. Missing the ability to successfully sync AD login events (only required for VA-based AD integration) may generate an error message on the connector "Access Denied". As long as the AD tree appears in the dashboard, this error may be ignored. Error message improvements specific to the roaming client AD integration use case are planned.

If more than one domain controller is registered, the connector and domain controllers (SD server) are displayed in an orange warning state. This is because they are not communicating with the remaining DCs. You can ignore this warning as long as at least one AD server is active (green)

OpenDNS_Connector User

You must also create a new user account with the following properties:

• The logon name (aka sAMAccountName) set to OpenDNS_Connector.
• Password never expires checked.
• A password entered without backslashes, quotations (single or double), greater-than or less-than "chevron" bracket characters ("<", ">") or colon characters.
• Confirm that the OpenDNS_Connector user is a member of the following group: Enterprise Read-only Domain Controllers. If it is not a member, add it to the group.

Running the Configuration Script on the Domain Controllers

1. Navigate to Deployments > Configurations > Sites and Active Directory and click Download.

2. Click Download for the Windows Configuration script for Domain Controller and save the file to a location on the machine you plan to run it.

Note: The configuration script is written in Visual Basic Script and is human readable. For reference, it automates the instructions listed in the knowledge base article Required Permissions for the OpenDNS_Connector User. For more information, contact Support.

This script is optional. The Umbrella support team can add registration records for all DCs without any script to run on any DC.

Requirements:

• Create a support ticket with:
  -- Attached CSV of all DCs to register in the format: name, internal IP, domain
  -- Attached .WSF script as downloaded from your dashboard
  -- Organization target to import to. For example, paste the URL at the top of your Dashboard
• Consult the Required Permissions for the OpenDNS_Connector User documentation since no automatic permissions are applied without the script.

🚧

Before Proceeding

The OpenDNS_Connector user must be created before running the script, as detailed in the prerequisites. There are also several group policies that affect system operation that may need manual configuration. The script will display the status of these settings and, if needed, provide instructions on changing them.

3. As Admin, open an elevated command prompt.
4. From the elevated command prompt, enter: cscript <filename> --forcenonva true
   Where is the name of the configuration script you downloaded earlier and --forcenonva true to skip the permissions needed for VA deployment.

👍

Tip

If you receive the error message "Please verify that the Domain Controller can access the Umbrella API (67.215.92.210, 146.112.255.155) at port 443!" and port 443 is confirmed to be open to api.opendns.com, crl4.digicert.com, and ocsp.digicert.com, the DC may be missing the DigiCert CA. To confirm, visit https://api.opendns.com/v2/OnPrem.Asset in the browser and if a certificate error is presented, download and install the latest DigiCert CA from DigiCert here and re-run the configuration script.

Verify that the Domain Controller is Reporting

Verify the DC in the dashboard by checking for the hostname of the domain controller you just ran the script on is in the Inactive state on the Active Directory Configuration page.

Note: The configuration script only runs once; it is not an application or service. If you change the IP address or hostname of the domain controller, remove the previous instance of the domain controller by clicking the round X icon to delete it from the Umbrella dashboard. Then repeat tasks 1 through 5 above in order to re-register the domain controller.

Install the Connector

1. Navigate to Deployments > Configuration > Sites and Active Directory and click Download.

2. Click Download for the Windows Service archive.
   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.
3. As an Admin, extract the contents of the ZIP file you downloaded to a folder.
4. Navigate to that folder.
5. Run setup.msi.
6. Enter the password you configured for the OpenDNS_Connector user you created earlier in these steps.
7. Follow the setup wizard prompts.
8. When finished, click Close.
9. Return to the dashboard.

Verify the Connector Syncs with the Dashboard

👍

Tip

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 DC may be missing the DigiCert CA.
To confirm, visit https://api.opendns.com/v2/OnPrem.Asset in the browser and if a certificate error is presented, download and install the latest DigiCert Global Root CA from DigiCert here and restart the Connector service. If it does not appear, contact support.

1. Navigate to Deployments > configuration > Sites and Active Directory.
   You will see the hostname of the Domain Controller or other Windows machine that you installed the Connector.
2. Navigate to Policies.

• The Domain Controllers (or other Windows machine) should automatically synchronize user and computer group memberships, and any subsequent changes, with Umbrella through the connector. You can verify that this has occurred successfully by clicking add a new policy and confirming that your groups are present.
• You should see all of your AD groups, included those nested within other groups, within the identity picker of the policy wizard.
• If you don’t see your groups, check the Active Directory Configuration page to see if the status of all components is Active (green). If not, contact [email protected].

Note: It can take up to two hours for large numbers of AD user, computer and group objects to synchronize for the first time.

Identity Support for the Roaming Client < Connect Active Directory to Umbrella for Roaming Clients > Appendix A – Status and Functionality