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

The Umbrella Wireless LAN Controller (WLC) guide provides instructions to set up and manage the integration of the Wireless LAN Controller with Umbrella.


The Umbrella Wireless LAN Controller interface refers to Cisco Umbrella as OpenDNS. Within this guide, we refer to the feature within the Wireless LAN Controller user interface as OpenDNS and the Umbrella dashboard and DNS service as Cisco Umbrella or Umbrella.

Note: During registration, the WLAN creates network devices in the Umbrella dashboard, with the format <WLC name>_<profile name> where <profile name> is the OpenDNS Profile. The WLAN integration instructions describe how to manually assign network devices to an Umbrella policy. Alternatively, if an Umbrella policy exists in the Umbrella dashboard before registration, and exactly matches the <WLC name>_<profile name> output from the WLAN controller, then Umbrella automatically places the network device in the matching Umbrella policy. You can also update a network device and policy through the Umbrella Network Devices and Policies API.


  • AireOS 8.4: The Cisco Wireless LAN Controller requires AireOS 8.4 or a newer version to support Cisco Umbrella WLAN. In order to upgrade to AireOS 8.4, you must have AireOS 8.0 or a later version.
  • 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. For more information, see the Cisco Wireless LAN Controller Configuration Guide.
  • For initial registration, the public-facing external interface of the WLC requires access to over port 443 in order to complete the initial registration.
  • TCP and UDP on port 53 (DNS) to reach the Cisco Umbrella public DNS resolvers: and
  • DNSCrypt—If there are any devices in front of the ISR that may block DNSCrypt, the DNSCrypt feature may not work. For more information, see Cisco ASA Firewall Blocks DNSCrypt.
  • An administrator account for the Cisco Umbrella dashboard.

Note: The information in this guide was created from deploying 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—An Umbrella Legacy Network Devices API token is issued through the Cisco Umbrella dashboard. Umbrella requires the API token to register a network device.
  • Device Identity—A unique device identifier. Umbrella enforces a policy for each identity.
  • EDNS—An extension mechanism for DNS which carries a tagged DNS packet.
  • FQDN—Fully Qualified Domain Name (for example:

Wireless LAN Controller Setup and DNS Request Flow

For any internet data request, a DNS request always precedes a web (HTTP) request. The Wireless Lan Controller intercepts the DNS request from the client and redirects the query to Umbrella. The Umbrella DNS resolvers are located at and The Umbrella 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. Register the Wireless LAN Controller with the Umbrella server. The WLC registration is a one-time process that occurs over a secure HTTPS tunnel. Create a Legacy Network Devices API token from the Umbrella dashboard.
  2. Apply the API access token on the Wireless LAN Controller. With the access token applied, the WLC registers the device to the Umbrella account. Create Umbrella Profiles on the WLC. The Wireless LAN Controller automatically pushes Profiles to Umbrella as identities. An Umbrella policy is enforced for each identity.
  3. Wireless client traffic flows from the Umbrella server. A wireless client sends a DNS request to the Wireless LAN Controller. WLC reads the DNS packet and tags it with an Umbrella Profile. The Umbrella Profile represents the identity of the packet which also resides on OpenDNS. This EDNS packet is redirected to the Umbrella cloud server for name resolution.
  4. If a policy is enabled for this identity, Umbrella applies the category-based filtering rules to ensure organizational compliance.
  5. Depending on the policy and whether a destination is considered malicious, Umbrella either returns the IP of a block page or resolved IP address to the client for the DNS request queried.

Configure the Wireless LAN Controller Integration

  1. To provision a network device with Cisco Umbrella, you must create an Umbrella user account. For information about Umbrella subscriptions, see Cisco Umbrella Packages.
    Note: Permanent License is covered under CiscoOne Advanced Subscription.
  2. Enable the Wireless LAN Controller (GUI or CLI) for Cisco Umbrella.
  3. Configure profiles (identities) on the Wireless LAN Controller. You can map a profile to either WLAN, AP Group, or incorporate the profile into a Local Policy.
  4. The Wireless LAN Controller redirects DNS packets to the Cisco Umbrella cloud.
  5. Umbrella applies enabled policies for each identity. To integrate the Wireless LAN Controller with Cisco Umbrella, you must add the Umbrella Legacy Network Devices API Token to the device, create an Umbrella profile, and map the profile to either WLAN, AP Group, or Local Policy.
    The policy priority order—from highest to lowest—is:
    • Local Policy
    • AP Group
    • WLAN

The Cisco Umbrella profile, when mapped to a Local Policy, allows for a granular differentiated user browsing experience based on the dynamic evaluation of attributes (user role and device type).

Sample Wireless LAN Controller Deployments

  • Scenario 1—Configure WLC for Cisco Umbrella and add a Cisco Umbrella profile in a user role based Local Policy.
  • Scenario 2—Configure WLC for Cisco Umbrella and add a Cisco Umbrella profile on a WLAN and AP Group.

Scenario 1: Configure Local Policies for Cisco Umbrella

For users in an organization, our goal is to restrict internet access to certain destinations based on their role types. In this scenario, we create two types of role: contractor and employee.

We use an external AAA server to authenticate a user and based on the identity, pass the user role as either contractor or employee to the WLC. On the WLC, configure two policies: employee and contractor. You can apply a different Cisco Umbrella profile to each policy to restrict their browsing activity when connected to the same dot1x enabled WLAN. To achieve this, take these steps:

  1. In the Umbrella dashboard, generate a Legacy Network Devices API token for device (WLC) registration.
  2. In the WLC, enable OpenDNS globally, apply the API token, and create OpenDNS profiles for employee and contractor.
  3. In the Umbrella dashboard, add policies for employee and contractor and select category definitions for each policy.
  4. In the WLC, create a Local Policy for employee and contractor and assign the AAA returned role and OpenDNS profile under each.
  5. In the WLC, assign the two local policies to the dot1x WLAN.


  1. In the Umbrella dashboard, 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. Locate the DNS Server IP field and enter an IP address for a DNS server that can resolve domains. This step is required before you can enable the Cisco Umbrella feature on the WLC.
  1. From the WLC main menu, navigate to Security > OpenDNS > General > enable OpenDNS Global Status.
    Note: The Wireless LAN Controller CLI command is: config openDNS enable.
  2. Add your Umbrella API token to the OpenDns-ApiToken field.
  1. On the same page, under Profile, create OpenDNS profiles and click Add.
    Note: The Wireless LAN Controller CLI command is: config openDNS profile create <*profile-name*>.

For this example, create two OpenDNS profiles: employee (employeeOD) and contractor (contractorOD) through the CLI or GUI. These profiles are automatically pushed to your Umbrella account as identities. You can see the state of the profiles populated as Profile Registered.
Note: Automatic profile registration depends on a successful connection between the WLC and Umbrella.

Verify the two profiles.

Note: Each OpenDNS Profile has a unique Opendns-Identity. The Wireless LAN Controller generates the OpenDNS-Identity as: <WLC name>_<profile name>. The WLC pushes the profile to the corresponding Umbrella account.

a. In the Umbrella dashboard, navigate to Deployments > Core Identities > Network Devices. In the table, locate the Device Name column. Verify that Umbrella lists two identities: <WLC name>_employeeOD and <WLC name>_contractorOD.

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.

In this example, we create the employeeCategory and contractorCategory settings.

The employeeCategory rule blocks certain content categories (for example: Adult themes, Adware, and Gambling). The contractorCategory rule blocks additional destinations, including: 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 category, see Manage Content Categories.

  1. In Umbrella, add two new policies:
    • EmployeePolicy: Assigns the employeeOD identity and includes the employeeCategory category settings.
    • ContractorPolicy: Assigns the contractorOD identity and includes the contractorCategory category settings.

For more information about policies, see the 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 click 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 click Set & Return to return to the policy's Summary page.

  1. Configure User Roles on an Identity Services Engine (SE).
    a. Configure an AAA server or Identity Services Engine (ISE) to allow users to be 802.1x authenticated. The AAA server or ISE returns the ROLE string back to the Wireless LAN Controller for local policy enforcement.
    On the ISE, navigate to Administration > Identity Management > Identities. Configure the employee and contractor users.

b. Next, navigate to Administration > Identity Management > Groups. Configure the Employee and contractor groups.

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 or reject) and user role (employee or contractor) as shown above.

  1. Configure local policies for OpenDNS.
    Configure a user role-based local policy and assign the OpenDNS profile to it. Finally, map the local policy to a WLAN.

a. On the Wireless LAN Controller, create two local policies: employee and contractor. From the WLC main menu, navigate to Security > Local Policies and click New.

b. Create a local policy named employee. Click Apply.

c. Create a local policy named contractor. Click Apply.

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 drop-down 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 drop-down 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 the Priority Index field to 1 and select employee from the Local Policy drop-down list. Click Add.

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

As a result, the WLC associates a user logging in with employee credentials with the "role = employee". This user inherits the employee OpenDNS profile (employeeOD). Similarly, a user logging in with contractor credentials assumes the "role = contractor" and inherits the 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. Navigate to WLAN > Advanced and select Forced in the OpenDNS Mode drop-down list.

d. Verify the following:

  • Connect a client to your WLAN with the employee user credentials.
  • Try accessing sites that are blocked under the category filtering rules you created for employee. For blocked sites, client receives a block page stating the site or domain is restricted.
  • Next, connect a client to your WLAN with the contractor user credentials. Repeat the test. You will notice the difference in browsing access granted to an employee versus a contractor.

Scenario 2: Configure WLAN or AP Group for Cisco Umbrella

Similar to the setup of the Local Policy, the OpenDNS profile attaches to a WLAN or AP Group. The following screenshots show how to assign the OpenDNS profile to a WLAN or AP Group. In the example, we assume that the OpenDNS account is already created and that you have copied the API token to the Wireless LAN Controller.


  1. From the WLC main menu, navigate to Controller > General. Locate the DNS Server IP field and enter an IP address for a DNS server that can resolve domains. This step is required before you can enable the OpenDNS feature on the WLC.
    Note: The Wireless LAN Controller CLI command is: config opendns server-ipv4 primary <*primary-server*> secondary <*secondary-server*>.
  1. Enable OpenDNS globally on the WLC. On the WLC menu, navigate to Security > OpenDNS > General.
    Note: The Wireless LAN Controller CLI command is: config openDNS enable.
  1. Configure API Token obtained from Cisco Umbrella account.
    Note: The Wireless LAN Controller CLI command is: config openDNS api-token <*token*>.
  1. Create OpenDNS Profiles.
    Note: The Wireless LAN Controller CLI command is:config openDNS profile create <*profile-name*>.
  1. Map the Profile to WLAN or AP Group.
    a. To assign the OpenDNS profile to a WLAN, navigate to WLANs > WLAN Id > Advanced. In the OpenDNS Profile drop-down list select the contractorOD profile.
    Note: The Wireless LAN Controller CLI command is: config wlan opeDNS-profile <*wlan-id*> <*profile name*> enable.

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

In the screenshot below, the WLC menu displays AP Group APgrp1 and maps contractorOD OpenDNS profile to WLAN 1.

Note: The Wireless LAN Controller CLI command is: command:config wlan apgroup opendns-profile <*wlan-id*> <*site-name*> <*profile-name*> enable.

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

The OpenDNS Profile contractorOD maps to WLAN ID 1.

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

Note: From the WLC CLI:

OpenDNS WLAN configuration modes

Through the WLAN Advanced tab, an administrator can configure OpenDNS on a WLAN in three modes.

  1. DHCP Proxy for DNS override.
    Interface level config. Part of the DHCP process to propagate the OpenDNS IP address to all WLANs associated to the interface. The override occurs 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 (Cisco Umbrella cloud servers, or enterprise or external DNS servers) used by the client.
  4. OpenDNS Copy mode (not included in 8.4 release).
    A copy of OpenDNS packets where all internet bound DNS traffic forwards to Cisco Umbrella cloud servers without any policy options (no block or 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, or locate users trying to access restricted 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 Get Started with Reports.

Cisco Umbrella Support

  • WLC supported platforms. For more information, see Prerequisites.
  • 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 a DNS query to resolve the server address is not subject to the Umbrella policy framework.
  • An application or host that directly uses an IP address instead of a DNS to query domains is not enforced with an Umbrella security policy.

Integration for ISR 4K and ISR 1100 – Security Configuration Guide < Wireless LAN Controller Integration > Meraki Cloud-Managed Networks and Umbrella

Updated 6 months 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.