The Umbrella Deployment Documentation Developer Hub

Welcome to the Umbrella Deployment Documentation developer hub. You'll find comprehensive guides and documentation to help you start working with Umbrella Deployment Documentation as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Appendix A – Communication Flow and Troubleshooting

As our integration spans several areas of your Active Directory (AD) configuration, it can be helpful to understand the flow of communication between each of the operational components. This can assist in troubleshooting and in ensuring that your environment is properly configured pre-deployment.

What is Synced with AD?

Only the AD users, groups, and computer details are synced. These are posted securely to the Umbrella API and are required to perform mapping of DNS requests to their users for logging and filtering purposes. No other AD information or AD attributes are synced with us.

To find out exactly what is being synced, you can look at the .ldif files contained within C:\Program Files\OpenDNS\OpenDNS Connector\ADSync.

When the Connector Script is Run on a Domain Controller

The Windows Connector script will make a one-time connection from the domain controller to the Umbrella cloud on port TCP/443 using HTTPS. This is to register the domain controller (DC) to the dashboard so that the connector knows about it. We make a call to: https://api.opendns.com with some specific parameters.

Once the script successfully registers the DC, you should see it listed at Deployments > Configuration > Sites and Active Directory.

We have previously seen issues that can be related to the "Root Certificate Updates" on Windows. A quick way to determine if you are seeing this behavior is to open Internet Explorer and point the browser to https://api.opendns.com/v2/OnPrem.Asset.

The page should provide a message similar to "1005 Missing API key".

If there are any certificate errors or warnings seen on that page, make sure that you have the latest "Root Certificates Update" from Microsoft installed.

How the AD Connector Communicates with the Umbrella Cloud Service or a Virtual Appliance

Connector > Cloud

The connector uploads all AD data every two minutes if there are changes, using an HTTPS connection on port 443 TCP. We only upload information on Groups/Users/Computers; no passwords are uploaded and all user information is hashed locally so that the data is unique to us. Although data is submitted to the Umbrella cloud service every two minutes, changes can take several hours to appear in the dashboard.

Connector > Virtual Appliances

The connector constantly sends AD events to the virtual appliances (VAs) using port 443 TCP. This is a one-way communication; the appliances will not talk back to the connectors. Logs from the connector are sent to the VAs on port 8080 TCP.

The connector currently sends information, including IP to username mappings, to the VA in unencrypted form. A mandatory pre-requisite for AD integration with the VA is that the connector and VA should communicate over a trusted network.

Connector > Domain Controllers

The connector will talk to all domain controllers that are located in the same site using ports 389 TCP and 3268 TCP/UDP for LDAP sync. The connector also communicates with the domain controllers using RPC/WMI. In general, port 135 TCP is the standard port for RPC and WMI.

Based on your AD version, WMI also uses a randomly assigned ephemeral port: either between 1024 TCP and 65535 TCP for Windows 2003 and older or between 49152 TCP and 65535 TCP for Windows 2008 and above.

Starting with version 1.1.24, the connector can also communicate to the domain controller using LDAPS (LDAP over SSL) over ports 636 TCP and 3269 TCP. The connector will first attempt to communicate to the domain controller over LDAPS and if unsuccessful, it will fall back to communicating over LDAP using Kerberos or NTLM in that order.

If any issues are seen around communication, we recommend checking for any Layer-7 application proxies that might be blocking/dropping some data. A common case is the inspect feature on Cisco devices that act on protocols such as DNS/HTTP/HTTPS:
http://www.cisco.com/c/en/us/td/docs/security/asa/asa72/configuration/guide/conf_gd/inspect.html

If any changes are made to the domain controllers’ audit policy to change the user login/logout events reporting, it is recommended that you restart the connector to eliminate any issues around communication channels.

Virtual Appliances to the Cloud, Other Internet Destinations, and Internal DNS Servers

The VAs will frequently communicate with the Umbrella APIs on port 443 TCP to api.opendns.com. They will also receive updates from disthost.opendns.com and disthost.umbrella.com on port 443. The VAs receive data from the connectors on port 443 TCP but do not require communication back to the connector.

Additionally, the VAs need to communicate on on port 22, 25, 53, 80, 443 or 4766 TCP to s.tunnels.ironport.com to establish a support tunnel under the new model. The VA will also forward internal DNS requests to your internal DNS servers. Ensure that port 53 UDP is open between the VA and your internal DNS server.

The following table lists ports, with source/destination of the request and the function of the request:

Port
Source/Destination
Function

53/UDP
53/TCP

208.67.222.222, 208.67.220.220
(outbound)

Local clients
(inbound)

Internal DNS
(outbound)

  • Send and receive DNS queries.

  • Outbound DNS queries to Umbrella will be encrypted using DNSCrypt if possible, and thus may trigger packet inspection rules.

443/TCP

api.opendns.com

disthost.opendns.com
(outbound)

disthost.umbrella.com (outbound)

  • Initial registration with the Umbrella API and the Umbrella dashboard.
  • Automatic updates

  • Health status reporting in the Umbrella dashboard.

123/TCP

ntp.ubuntu.com

  • NTP. Used only during boot.

80/TCP

ocsp.digicert.com, crl3.digicert.com, *crl4.digicert.com
(outbound)

*Required for SSL Revocation verification as part of the HTTPS handshake.

22 25 53 80 443 or 4766 TCP

s.tunnels.ironport.com

Note: The Digicert domains resolve to various IP addresses based on a CDN and are subject to change. Currently, these domains resolve to 72.21.91.29, 117.18.237.29, 93.184.220.29, and 205.234.175.175.

If you are utilizing AD components (as opposed to just using the VAs for internal IP address granularity), the following extra inbound network traffic will also occur from the AD connector service.

Port
Source/Destination

443/TCP
8080/TCP

AD Connector
(inbound)

Send information relating to login events and IP addressing. This traffic occurs over 443/TCP, but is not an HTTPS connection. Many IDS and IPS systems flag this traffic as suspicious; if you're running an IDS or IPS that is listening on the local network, check the enforcement logs to ensure this traffic is not getting blocked.

AD Connector Service

Port
Source/Destination
Function

389/TCP
3268/TCP
636/TCP
3269/TCP
135/TCP
1024-65535/TCP (Server 2003)
49152-65535/TCP (Server 2008/2012)

AD Servers (Domain Controllers)
(outbound)

  • WMI/RPC/DCOM communication between Domain Controllers.

  • LDAP syncing

443/TCP
(Non-SSL)
8080/TCP

Virtual Appliances
(outbound)

Send information relating to login events and IP addressing. It's very important to note that this traffic occurs over 443/TCP, but is not an SSL connection. Many IDS and IPS systems will flag this traffic as suspicious. If you're running an IDS or IPS that is listening on the local network, check the enforcement logs to ensure this traffic is not getting flagged.

443/TCP

api.opendns.com

disthost.opendns.com
(outbound)

disthost.umbrella.com
(outbound)

  • Initial registration with the Umbrella API and the Umbrella dashboard.

  • Automatic updates

  • Health status reporting in Umbrella dashboard.

80/TCP
80/UDP

crl.comodoca.com
ocsp.comodoca.com
crl.usertrust.com
ocsp.usertrust.com

Required to maintain the Online Certificate Status Protocol (OCSP) and certificate revocation lists (CRL) portion of the SSL Revocation.

80/TCP

ocsp.digicert.com, crl3.digicert.com, *crl4.digicert.com
(outbound)

Required for SSL Revocation list verification as part of the HTTPS handshake.

Note: The Digicert domains resolve to various IP addresses based on a CDN and are these subject to change. Currently, these domains resolve to 72.21.91.29, 117.18.237.29, 93.184.220.29, and 205.234.175.175

AD Servers (Domain Controllers)

Port
Source/Destination
Function

389/TCP
3268/TCP
636/TCP
3269/TCP
135/TCP
1024- 65535/TCP
(Server 2003)
49152-65535/TCP
(Server 2008/2012)

AD Connector(s)
(inbound)

  • WMI/RPC/DCOM communication between Domain Controllers.
  • LDAP Syncing

443/TCP

api.opendns.com
(outbound)

Initial registration with the Umbrella API.

80/TCP

ocsp.digicert.com, crl3.digicert.com, *crl4.digicert.com
(outbound)

Required for SSL Revocation list verification as part of the HTTPS handshake.

Note: The Digicert domains resolve to various IP addresses based on a CDN and are these subject to change. Currently, these domains resolve to the following IPs: 72.21.91.29, 117.18.237.29, 93.184.220.29, 205.234.175.175

What Does the Umbrella Windows Connector Script Do?

The Windows Connector script sets specific user permissions for the OpenDNS_Connector user. When the user is deleted, the script's impact is deleted. If you are running the script in a strictly controlled AD environment, some administrators may not be permitted to run VB scripts. If this is the case, contact Support.

Visual Overview

The following diagram provides a general outline of how traffic flows between components in the Umbrella Active Directory Integration.

SSH Support Tunnel – Allowing and Blocking the Tunnel

As of version 2.1.0 of the VA (September, 2017), there is a new SSH Support tunnel. The new tunnel must be established by the customer to the Cisco support team and otherwise is not available. For more information, see On-Demand Tech Support SSH Tunnel for Virtual Appliances.


5. Route DNS Traffic < Appendix A – Communication Flow and Troubleshooting > Appendix B – Multiple Active Directory and Umbrella Site