The Umbrella User Guide Developer Hub

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

Get Started    

Active Directory User Exceptions

Many organizations use service accounts in order to perform scheduled tasks or automatic updates. If a user logs in while a service account is performing a scheduled task, the login event will be attributed to the service account. The result is that the policy for the service account will be applied instead of that of the user who is actively logged in and using the computer. The Active Directory User Exception should be applied to service accounts within your organization so that their login events to your Domain Controllers are ignored by the AD Connector.

Active Directory user exceptions are best used for:

  • Service accounts that perform scheduled tasks: for example, software backups
  • Service accounts that need to log in to the network to perform updates: for example, anti-virus clients
  • Adding the IPs of RODCs which mirror events

Note: Do not use this feature with any user accounts you wish to have the login events recorded for, or accounts whose activity you wish to see in the reporting and that should have a policy applied to them.

Table of Contents


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.
  • AD Domain Services Snap-ins and Command-line Tools feature installed through Remote Server Administration Tools > Role Administration Tools > AD DS & AD LDS Tools > AD DS Tools. This is required for troubleshooting purposes

If you are deploying AD integration with Virtual Appliances through integration with domain controllers, you will need to deploy one connector per AD domain (with an optional second connector per AD domain for redundancy).

If you have already deployed a centralized Windows Event Log Collector to which all domain controllers forward login events, and you wish to deploy AD integration with Virtual Appliances using this Windows Event Log Collector, you will need to deploy a single AD connector for all AD domains, with an optional second connector for redundancy.

Outbound Network Access to Cisco Umbrella

The Connector server requires outbound access as specified below:

  • 443 (TCP) to 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 the section on Communication Flow and Troubleshooting.
  • 443 (TCP) to (for downloading upgrades)

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

  • The logon name (sAMAccountName) set to OpenDNS_Connector. A custom username can be configured, but this custom username should be specified as a parameter when running the Configuration Script on the Domain Controller.
  • Password never expires selected
    Note: Passwords must not include backslashes, quotations (single or double), greater-than or less-than chevron brackets (< >), or colons.
  • The Connector account (OpenDNS_Connector or custom username) must be a member of the following built-in groups on each AD domain:
    • Enterprise Read-only Domain Controllers
    • Event Log Readers

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 Connector account. You must add other missing groups.

Set Up Active Directory User Exceptions

  1. Navigate to Deployments > Configurations > Service Account Exception and click Add.
  1. Under Account Type, choose User.
  2. Under Value, enter the AD Username or login (sAMAccountName) for the account in the format "Username" (not "[email protected]").
    Note: This is not necessarily the same account name as the one displayed in the AD Users Identities in the dashboard. Confirm the account username in the Active Directory Users and Computers snap-in, not the Umbrella dashboard.
  1. Enter an optional description and click Create.
    Note: In multi-AD domain environments, any user exception (sAMAccountName) configured will be blocked for all AD domains.

Set Up Active Directory Group Exceptions

You can add Active Directory Groups to the exception list. The Connector will ignore login events generated by all users and computers belonging to the specified group and any sub-groups and exclude them from the AD mappings. This can be used for AD groups that comprise only service accounts, so that the individual service accounts need not be specified as exceptions.
Note: Adding Active Directory Organization Units (OUs) is not supported.

  1. Navigate to Deployments > Configurations > Service Account Exception and click Add.
  1. Under Account Type, choose Group.
  2. Under Value, enter the Distinguished Name (DN) for the AD group that you want to add as an exception. For example, enter the AD group name as CN=Engineering,CN=Builtin,DC=mydomain,DC=com.
    Note: This is not the same format as the one displayed in the AD Groups Identities in the Umbrella Dashboard. Please confirm the group DN in the Active Directory Users and Computers snap-in, not the Umbrella Dashboard. The group DN is case sensitive. You can also use this Powershell command to confirm the distinguished name for AD groups:
    Get-ADGroup -Identity <ADGroupName>
  1. Enter an optional description and click Create.

Set Up Active Directory IP Address Exceptions

IP addresses can also be added to the Exceptions list. The Connector will ignore all the events generated by the configured IP to exclude it from the AD mappings. An example use case would be the IP address of a Netscaler server or a RODC that mirrors events.

  1. Navigate to Deployments > Configurations > Service Account Exception and click Add.
  1. Under Account Type, choose IP.
  2. Under Value, enter the IP address.
    Note: IP address ranges are not supported. Only individual IP addresses, such as, are supported.
  1. Enter an optional description and click Create.

Prerequisites < Active Directory User Exceptions > Prepare Your Active Directory Environment

Updated 3 months ago

Active Directory User Exceptions

Suggested Edits are limited on API Reference Pages

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