The Umbrella Documentation Hub

Welcome to the Umbrella documentation hub. Here you'll find our comprehensive guides designed to help you use with Cisco Umbrella.

Get Started    

Prerequisites

Active Directory Environment

To support Umbrella Active Directory (AD) integration, you must configure the following AD environment:

  • Windows Server 2008, 2008 R2, 2012, 2012 R2, 2016 or 2019 with the latest service packs and 100MB free hard disk drive space. Service packs prior to SP2 are not supported.
  • .NET Framework 3.5, 4.0, 4.5, or 4.7
  • If a local anti-virus application is running, the processes OpenDNSAuditClient.exe and OpenDNSAuditService.exe should be allow listed.

Important

For Read Only Domain Controllers (RODCs) with Global Catalog server, run the script with the option "--forcenonva true" only if it is a roaming client only deployment. RODCs should not be used for virtual appliance AD integrations.

  • Multi-domain environments are supported in a single Umbrella organization. For more information about enabling multi-AD domain support in a single Umbrella organization, see Multi-AD Domain Support in Umbrella.
  • When deploying AD components at more than one WAN-linked (MPLS-type network) AD site, verify a complete, functioning installation at the current site before moving onto the next site.
  • A new user account in each AD domain that needs to be integrated. This account should have:
    • The logon name—also known as sAMAccountName—set to OpenDNS_Connector
    • Password never expires checked
      Note: Passwords must not include backslashes, quotations (single or double), greater-than or less-than chevron brackets (< >), or colons. You must keep the password for this account the same across all AD domains that need to be integrated with Umbrella.
    • The OpenDNS_Connector user must be a member of the following groups:
      – Enterprise Read-only Domain Controllers
      – Event Log Readers (only if the Connector will be used with VAs)
      – Distributed COM Users (only if the Connector will be used with VAs)
      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 OpenDNS_Connector account. You must add other missing groups.

Network Environment

For an overview of how the network topology is expected to work, as well as the flow of traffic, see Appendix A – Communication Flow And Troubleshooting.

Umbrella API Access

All Umbrella AD components—specifically, VAs, connectors, and domain controllers—require access to the Umbrella API. The following network requirements must be in place:

Domain Controllers

Each AD domain controller—excluding read-only domain controllers—needs to perform a one-time registration with the Umbrella API. For the registration script to succeed, access to the Umbrella API must be available.

If network restrictions do not permit your AD domain controllers from communicating with the Umbrella API, create a Support ticket with Cisco Umbrella and request that your domain controllers be registered offline.

Connector Server

A connector must be installed at each Umbrella site on a Windows server or workstation. The purpose of the connector is to read information from the registered domain controllers and report this to the VA and Umbrella API. If there are multiple AD domains within your Umbrella site, a Connector must be deployed for each AD domain in the Umbrella site. In addition to the requirements above, the connector requires access to the following:

  • LDAP Sync—the Connector Server will talk to all domain controllers that are located in the same site using ports 389/636 TCP and 3268/3269 TCP/UDP for LDAP sync or LDAP over SSL.
  • If your deployment includes VAs:
    • A Connector must be deployed for each AD domain in the Umbrella site.
    • The connector must communicate with the VA over a trusted network.
    • The connector communicates over port 443 (TCP) and 8080 (TCP) to the VAs.
    • 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.

Updates

The connector is capable of automatic updates. To download updates, the connector requires access to the following URL:

  • 443 (TCP) to disthost.umbrella.com

Additional Considerations

Do not place devices with network address translation (NAT), or that in any manner obfuscate the internal IP address, between hosts and the VA per site.

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.

Set the ‘Audit Policy Set: True/False’ Group Policy

You may also need to set the "Audit account logon events" to include Success and Failure if it has been set to "No Auditing." By default, this group policy is set to log Success logon events and you should not modify it if that's already the case.

This is needed by the Umbrella software so that it knows whether a user has logged in successfully and can then compare that log in to subsequent events generated by that user.

For more information, see Audit account logon events.

The error you will see when running the OpenDNS Windows Configuration Script OpenDNS-WindowsConfigurationScript-20130627.wsf if the Audit Policy is not set is:

"ERROR: "

-----------------------------------------------------------------------------
Your Group Policy for this Domain Controller is set to NOT audit successful logon events!
You MUST edit the following Group Policy for all DCs:

Computer Configuration\Policies\Windows Settings\Security Settings\Local Policies\Audit Policy\Audit logon events

Define that policy to audit Success attempts, gpupdate, and re-run this script!
*------------------------------------------------------------------------------

This policy SHOULD be set for 2003, but consider it just a warning
If (gManageELPSet = False) Then
WScript.Echo ""
WScript.Echo "ERROR: "
WScript.Echo "*------------------------------------------------------------------------------"
WScript.Echo "You must edit the following Group Policy and apply it to all 2003 DCs: "
WScript.Echo ""
WScript.Echo " Computer Configuration\Policies\Windows Settings\Security Settings\"
WScript.Echo " Local Policies\User Rights Assignment\Manage auditing and security log"
WScript.Echo ""
WScript.Echo "You must add the " & ACCOUNT_NAME & " user to the setting and gpupdate!"
WScript.Echo "*------------------------------------------------------------------------------"
WScript.Echo ""
End If

Other errors you may receive from running the script include:

WScript.Echo

WScript.Echo "Could not determine Domain Functional Level!"
WScript.Echo "Please try the --forceFL [2003|2008|2012] flag."

 WScript.Echo "WARNING:"
WScript.Echo "*-----------------------------------------------------------------------"
WScript.Echo "Cannot automatically configure WMI permissions for Win2003 OS."
WScript.Echo "You must do this manually via the WMI MMC Snapin (wmimgmt.msc)."
WScript.Echo "See the documentation for details."
WScript.Echo "If this is your only warning/error, you may continue with registration."
WScript.Echo "*-----------------------------------------------------------------------"
WScript.Echo ""

Updated 3 months ago

Prerequisites


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.