The OpenDNS Hardware Integrations Developer Hub

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

Get Started    

Wireless LAN Controller Integration

This document introduces Cisco Umbrella Wireless LAN Controller (WLC) Integration and provides general guidelines for its deployment. The purpose of this guide is to:

  • Provide an overview of OpenDNS WLC Integration feature
  • Highlight supported key features
  • Provide details on deploying and managing the OpenDNS feature on WLC
  • Help setup the Cisco Umbrella dashboard to manage the WLC in the web-based dashboard.


OpenDNS is now Cisco Umbrella; however, the feature described here is still named OpenDNS in the interface for the Wireless LAN controller. As such, this guide refers to "OpenDNS", "Cisco Umbrella", or simply "Umbrella" wherein all three are the same and thus interchangeable. In a future release, all names will be "Cisco Umbrella" or "Umbrella". As a rule of thumb, the feature within the WLC user interface is called 'OpenDNS', but the cloud-based dashboard and DNS service are both 'Cisco Umbrella'

Note: Automatic policy assignment based on Profile name - During registration, the WLAN will create Network Devices in the Umbrella dashboard, with the format <WLC name><profile name> where <profile name> is the OpenDNS Profile. The direction below describe how to manually assign these Network Devices to an Umbrella policy. Alternatively, if an Umbrella policy exists in the dashboard before registration, and exactly matches the <WLC name><profile name> output from the WLAN controller, then this Network Devices will automatically be placed in the matching Umbrella policy. Policy assignment can also be done via API.


  • AireOS 8.4 or newer is required on the Cisco Wireless LAN Controller to support Cisco Umbrella WLAN. Note: In order to upgrade to AireOS 8.4, customers must have AireOS 8.0 or higher release.
  • WLC supported platforms: 5508, 5520, 7500, 8510, 8540, 2504, 3504 (vWLC not supported).
  • Catalyst supported platforms: Catalyst 9100 AP with embedded controller, Catalyst 9800 controller. See the configuration guide.
  • For initial registration the public-facing external interface of the WLC must be able to access over port 443 in order to complete initial registration.
  • TCP & UDP on port 53 (DNS) to & (The Cisco Umbrella public DNS resolvers)
  • DNSCrypt—If there are any devices in front of the ISR that may block DNSCrypt for not looking like an actual DNS packet, the DNSCrypt feature may not work. For more information and an example of the problem, read here.
  • An admin account for the Cisco Umbrella dashboard

Components Used

The information in this document was created from devices in a specific lab environment. All of the devices used in this document started with a cleared (default) configuration. If your network is live, make sure that you understand the potential impact of any command.


  • API Token—Issued through the Cisco Umbrella dashboard. It is used for device registration.
  • Device Identity—A unique device identifier. Policy is enforced per identifier.
  • EDNS—An extension mechanism for DNS which carries tagged DNS packet.
  • FQDN—Fully Qualified Domain Name (eg:

How it works

For any internet data request, the DNS request always precedes web (HTTP) request. Wireless Lan Controller intercepts theDNS request from the client and redirects the query to the Cisco Umbrella (OpenDNS) server in the cloud. The Cisco Umbrella (OpenDNS) DNS resolvers are located at and The Umbrella (OpenDNS) service resolve the DNS query and enforces preconfigured security filtering rules on a per identity basis. If the domain is marked as malicious, Umbrella returns the IP of a block page to the client. If it is determined to be safe, Umbrella returns the resolved IP address to client.

The following diagram outlines the process of registration and DNS queries between an end client computer, through the WLC and to Cisco Umbrella.

  1. WLC registration with the Umbrella server is a one-time process and happens over a secure HTTPS tunnel.
  2. You must obtain an API Token for device (WLC) registration from the Umbrella dashboard.
  3. Next, apply the Token on the Wireless Lan Controller. This should register the device to the Umbrella account. Next, create Umbrella Profile/s on WLC. Profiles will automatically be pushed to the Umbrella dashboard as Identities and policy can be enforced on a per identity basis.
  4. Wireless client traffic flow from the Umbrella server.
  5. A wireless client sends a DNS request to WLC.
  6. WLC snoops the DNS packet and tags it with an Umbrella Profile. Profile is the identity of the packet which also resides on OpenDNS.
  7. This EDNS packet is redirected to the Umbrella cloud server for name resolution.
  8. Umbrella then enforces a policy on it depending on the identity and applies category-based filtering rules to ensure organizational compliance.
  9. Depending on the policy and whether a destination is considered malicious, the service either returns the IP of a block page or resolved IP address to the client for the DNS request queried.

Configure the OpenDNS Wireless LAN Controller Integration

  1. Cisco Umbrella provisioning involves creating a user account on Umbrella cloud. Subscription is per account. For more information about purchasing Umbrella, please contact Cisco sales.
    Note: Permanent License is covered under CiscoOne Advanced Subscription.
  2. Enable Wireless Controller (GUI or CLI) for Cisco Umbrella.
  3. Configure profiles (identities) on WLC. Profile can be mapped to either WLAN, AP group or incorporated into local policy.
  4. WLC redirects DNS packets to Cisco Umbrella cloud.
  5. Security policies on Cisco Umbrella are applied per identity. Cisco Umbrella configuration steps on Wireless Controller involve enabling Cisco Umbrella function, configuring API Token, creating Profile/s and mapping the profile to either a WLAN, an AP group or a Local Policy.
    The policy priority order—from highest to lowest—is:
    • Local Policy
    • AP Group
    • WLAN

The Cisco Umbrella profile, when mapped to local policy, allows for a granular differentiated user browsing experience based on the dynamic evaluation of attributes (user role, device type, etc). For the rest of this document, we will discuss the following scenarios:

  • Scenario 1—Configure WLC for Cisco Umbrella and incorporate a Cisco Umbrella profile in a user role based local policy. We will also touch upon basic configuration on Cisco Umbrella Server.
  • Scenario 2—Configure WLC for Cisco Umbrella and apply a Cisco Umbrella profile on a WLAN and AP Group.

Scenario 1: Configuring Local Policies for Cisco Umbrella

In an organization, our goal is to restrict internet access (for particular websites) to users based on their role types. For example, regular employees should be permitted full internet access barring sites such as adult, gambling, nudity. At the same time, contractor access should be more rigid, barring access to social websites, sports, and news, as well as adult, gaming, nudity, and other such sites.

We will be using an external AAA server to authenticate a user and based on the identity, pass the user role as either contractor or employee to WLC. On the WLC, a user will configure two policies (for employee and contractor) and apply a different Cisco Umbrella profile to each to restrict their browsing activity when connected to the same dot1x enabled WLAN. To achieve this, we will:

  1. In the Umbrella dashboard, generate an API token for device (WLC) registration.
  2. In WLC, enable OpenDNS globally, apply the API token and create OpenDNS profiles for employee and contractor.
  3. In the Umbrella dashboard, create category definitions/rules and policies for employees and contractors.
  4. In WLC, create Local policy each for employee and contractor tying the AAA returned role and OpenDNS profile under each.
  5. In WLC, tie the two local policies to the dot1x WLAN

Scenario 1 – Procedure

  1. Navigate to Admin > API Keys​ and click Create.
  1. Select Legacy Network Devices and click Create.
  1. Expand Legacy Network Devices, and then copy the API token—Your Key—so that you can complete the next steps.
    The API token is a long alphanumeric set of characters.
  1. From the WLC main menu, navigate to Controller > General and enter a DNS Server IP address that can resolve domains. This is required for the first time before enabling Cisco Umbrella feature on the WLC.
  1. From WLC main menu, navigate to Security > OpenDNS > General > enable OpenDNS Global Status. In the CLI, the command is 'config openDNS enable'
  2. Paste the API Token you copied from the Umbrella dashboard.
  1. On the same page, under Profile, create OpenDNS profiles and click Add.
    CLI command: config openDNS profile create <profile-name>
    For this example, create two OpenDNS profiles, one for employee (employeeOD) and another for contractor (contractorOD) through CLI or GUI.
    These profiles are automatically pushed to your Umbrella account as Identities and you should see the State of the Profiles populated as Profile Registered. This is subject to a successful connection between the WLC and Umbrella server.

On CLI, you can verify the two profiles as shown:

Note: Each OpenDNS Profile has a unique Opendns-Identity generated on controller (in the format <WLC name>_<profile name>) which will be pushed to the associated Umbrella account in the cloud.

a. In the Umbrella dashboard, navigate to Deployments > Core Identities > Network Devices and verify that your WLC with both Identities employeeOD and contractorOD show up under Device Name.

b. Next, create classification rules for employee and contractor user roles selecting the domains that should be blocked for both of these roles. Navigate to Policies > Policy Components > Content Categories.

We have created employeeCategory and contractorCategory for this exercise.

The employeeCategory is blocking certain content categories; for example, Adult themes, Adware, and Gambling. The, contractorCategory is more restrictive, blocking, Adult themes, Adware, Gambling, Games, News, and Social Networking. Expand employeeCategory to view its list of blocked categories. You can edit the list to add or remove categories. For a list of all categories and details for each, see Understanding Content Categories.

  1. In Umbrella, add two new policies:
    • EmployeePolicy
    • ContractorPolicy
      employeePolicy is assigned to employeeOD identity and tied to a category employeeCategory (created in the last step). Similarly, contractorPolicy is assigned to contractorOD identity and tied to a custom category contractorCategory created earlier.

For more information about policies, see documentation specific to your version of Umbrella:

a. Expand a policy.

b. Click Edit under Identities Affected to see all the identities/network devices (Pod#-WLC_employeeOD) mapped to this policy.
c. Make changes as required, and slick Set & Return to return to the policy's Summary page.

d. Click Edit under Content Setting Applied to verify content category settings.
e. Make changes as required, and slick Set & Return to return to the policy's Summary page.

  1. Configuring User Roles on ISE.
    a. Configure a AAA server or ISE to allow users to be 802.1x authenticated and have the server return ROLE string back to the wireless controller for local policy enforcement.
    As illustrated below, on the ISE, configure users, that is, employee and contractor:

b. Next, configure groups, that is, group Employee and contractor.

Note: In this section of ISE, we are testing with ISE internal users. If ISE is pointing to an external user database like Active Directory, the rule changes and points to the respective user AD group.

c. Create an ISE policy for a specific group of users with a desired role, that is, employee or contractor.

At this point, it is assumed that administrator has configured the necessary authentication rules on ISE/AAA server for wireless users to return Authorization Profiles including access type (accept/reject) and user role (employee/contractor) as shown above.

  1. Configure local policies for OpenDNS.
    Configure a user role based Local Policy and tie the OpenDNS profile to it. Finally, map the local policy to a particular WLAN.

a. Now create two local polices for employee and contractors on the WLC. From the WLC main menu, navigate to Security > Local Policies and click New.

b. Create Local Policy name as "employee" and "contractor" and click Apply.

c. Similarly, create another one for contractor.

d. Click the employee Local Policy and configure it with employee OpenDNS profile (employeeOD).

e. Under Match Criteria configure Match Role String as "employee" and under the Action list go to OpenDNS Profile. From the dropdown list, select "employeeOD" then click Apply.

f. Click Back to go to the Local Policy page and click the contractor policy.

g. Under Match Criteria, configure Match Role String as "contractor" and under Action, from the dropdown list OpenDNS Profile, select "contractorOD", then click Apply

  1. Configure OpenDNS on WLAN.
    a. From the WLC main menu, navigate to WLAN > WLAN ID > Policy-Mapping. Assign Priority Index 1 and Select employee from the Local Policy dropdown list and click Add.

b. Similarly, apply the contractor policy to the WLAN.

As a result, a user logging in with employee credentials will be associated with "role = employee" and will be inherit employee OpenDNS profile (employeeOD) on the WLC. Similarly, a user logging in contractor credentials will be associated with "role = contractor" and will be inherit contractor OpenDNS profile (contractorOD) on the WLC.

c. For the WLC to redirect all DNS for a WLAN to the OpenDNS server, the OpenDNS Mode must be set to Forced as shown below. This is done by navigating to WLAN > Advanced.

d. Verify the following:

  • Connect a client to your WLAN with employee user credentials.
  • Try accessing sites that are blocked under the category filtering rules you created for employee. For blocked sites, client will get a display page stating the site/domain is restricted.
  • Try to associate to the same WLAN using contractor user credentials and repeat the test. You will notice the difference in browsing access granted to an employee versus a contractor.

Scenario 2: Configuring WLAN/AP Group for Cisco Umbrella

Similar to Local Policy, the OpenDNS profile can be attached to a WLAN or to an AP group. The following screenshots show how to tie the OpenDNS profile to a WLAN and AP group. It is assumed that the OpenDNS account is already created and that you have copied the API token.


  1. From the WLC main menu, navigate to Controller > General and enter a DNS Server IP address that can resolve domains. This is needed for the first time before enabling OpenDNS feature on the WLC.
    The CLI command is "config opendns server-ipv4 primary <primary-server> secondary <secondary-server>".
  1. Enable OpenDNS globally on WLC by going to Security > OpenDNS > General.
    The CLI command is "config openDNS enable".
  1. Configure API Token obtained from Cisco Umbrella account.
    The CLI command is "config openDNS api-token <token>".
  1. Create OpenDNS Profiles.
    The CLI command is "config openDNS profile create <profile-name>".
  1. Map the Profile to WLAN or AP group.
    a. To tie the OpenDNS profile to a WLAN, navigate to WLANs > WLAN Id > Advanced and under OpenDNS Profile select the contractorOD profile created above.
    The CLI command is "config wlan opeDNS-profile <wlan-id> <profile name> enable".

b. To map the Profile to AP Group, go to WLANs > Advanced > AP Groups. Select the AP group you want and go to WLANs tab. Hover the mouse over the blue button on the right and select OpenDNS Profile.

In the screenshot below, we selected AP Group APgrp1 and mapped contractorOD OpenDNS profile to WLAN 1.

The CLI command is "command:config wlan apgroup opendns-profile <wlan-id> <site-name> <profile-name> enable".

c. To view OpenDNS mapping, navigate to Security > OpenDNS > General and click Profile Mapped Summary.

Here, the OpenDNS Profile contractorOD is mapped WLAN ID 1.

On the same OpenDNS Profile Map Summary page, under AP Group, profile contractorOD is also mapped to AP Group APgrp1.

From the CLI:

OpenDNS WLAN configuration modes

An administrator can configure OpenDNS on a WLAN in three modes through the WLAN advanced tab.

  1. DHCP Proxy for DNS override.
    Interface level config. Part of DHCP process to propagate OpenDNS ip address to all WLANs associated to Interface. Happens in the client join phase.
  2. OpenDNS Force mode: (Enabled by default)
    Enforced per WLAN, blocks intentional client activity after client has associated to WLAN.
  3. OpenDNS Ignore mode.
    WLC honors the DNS server used by the client; it could be Cisco Umbrella cloud servers or enterprise/ external DNS
  4. OpenDNS Copy mode (not included in 8.4 release).
    A copy of OpenDNS packets where all internet bound DNS traffic is forwarded to Cisco Umbrella cloud servers without any policy options (no block/redirect)

Cisco Umbrella Activity Reporting

An administrator can log into Cisco Umbrella to view and generate reports regarding the clients’ activity, find the infected devices, targeted users trying to access forbidden sites. These reports can be filtered by client identity, destination and source IP.

  1. Navigate to Reporting and select a report. For more information, see Getting Started with Reports.

Cisco Umbrella Support

  • WLC supported platforms (see Prerequisites, above)
  • AP mode supported–Local mode, Flex central switching.
  • 10 different Cisco Umbrella Profiles configurable on WLC
  • Guest (Foreign–Anchor) scenario, profile applies at Anchor WLC

Cisco Umbrella Limitations

  • A client connected to a web proxy that does not send DNS query to resolve the server address is not subject to Umbrella policy framework
  • Application or host that uses IP address directly instead of DNS to query domains are not enforced with Umbrella security policy.

Integration for ISR 4K – Security Configuration Guide < Wireless LAN Controller Integration > Integration for ISR G2 – Solution Guide for Umbrella

Updated about a year ago

Wireless LAN Controller Integration

Suggested Edits are limited on API Reference Pages

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