• If an application or host uses IP address directly instead of DNS to query domain names, policy enforcement is not applied.

• When the client is connected to a web proxy, the DNS query does not pass through the Cisco device. In this case, the connector does not detect any DNS request and the connection to the web server bypasses any policy from the Cisco Umbrella portal.

• When the Cisco Umbrella Integration policy blocks a DNS query, the client is redirected to a Cisco Umbrella block page. HTTPS servers provide these block pages and the IP address range of these block pages is defined by the Cisco Umbrella portal.

• User authentication and identity is not supported in this release.

• The type A, AAAA, and TXT queries are the only records that are redirected. Other types of query bypasses the connector. Cisco Umbrella Connector maintains a list of IP address that is known for malicious traffic. When the Cisco Umbrella roaming client detects the destination of packets to those addresses, it forwards those addresses to Cisco Umbrella cloud for further inspection.

• Only the IPv4 address of the host is conveyed in the EDNS option.

• A maximum of 64 local domains can be configured, and the allowed domain name length is 100 characters.

Before you configure the Cisco Umbrella Integration feature, ensure that the following are met:

• The device has a security K9 license to enable Cisco Umbrella Integration.

• The device runs the Cisco IOS XE Denali 16.3 software image or later.

• Cisco Umbrella subscription license is available.

• The device is set as the default DNS server gateway and needs to ensure that the DNS traffic goes through the Cisco device.

• Communication for device registration to the Cisco Umbrella server is via HTTPS. This requires a root certificate to be installed on the router. To download the DigiCert root certificate, go to https://www.digicert.com/kb/digicert-root-certificates.htm#roots. To download the scope API certificate, go to: https://letsencrypt.org/certs/isrgrootx1.pem

The Cisco Umbrella Integration feature provides cloud-based security service by inspecting the DNS query that is sent to the DNS server through the device. When a host initiates the traffic and sends a DNS query, the Cisco Umbrella Connector in the device intercepts and inspects the DNS query. If the DNS query is for a local domain, it forwards the query without changing the DNS packet to the DNS server in the enterprise network. If it is for an external domain, it adds an Extended DNS (EDNS) record to the query and sends it to Cisco Umbrella Resolver. An EDNS record includes the device identifier information, organization ID and client IP. Based on this information, Cisco Umbrella Cloud applies different policies to the DNS query.

The DNS packet sent from the Cisco device to Cisco Umbrella Integration server must be encrypted if the EDNS information in the packet contains information such as user IDs, internal network IP addresses, and so on. When the DNS response is sent back from the DNS server, device decrypts the packet and forwards it to the host.

You can encrypt DNS packets only when the DNScrypt feature is enabled on the Cisco device.

The Cisco device uses the following Anycast recursive Cisco Umbrella Integration servers:

• 208.67.222.222

• 208.67.220.220

• 2620:119:53::53

• 2620:119:35::35

The Figure 1 describes the Cisco Umbrella Integration topology.

Cisco Umbrella Integration provides security and policy enforcement at DNS level. It enables the administrator to split the DNS traffic and directly send some of the desired DNS traffic to a specific DNS server (DNS server located within the enterprise network). This helps the administrator to bypass the Cisco Umbrella Integration.

You can configure Cisco Umbrella Connector using either the API tokens, or scope API keys.

To configure Cisco Umbrella Connector using API token:

• Get the API token from the Cisco Umbrella registration server.

• Have the root certificate establish the HTTPS connection with the Cisco Umbrella registration server. Import the root certificate of DigiCert given below into the device using the crypto pki trustpool import terminal command.

-----BEGIN CERTIFICATE-----
MIIDjjCCAnagAwIBAgIQAzrx5qcRqaC7KGSxHQn65TANBgkqhkiG9w0BAQsFADBh
MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMRkwFwYDVQQLExB3
d3cuZGlnaWNlcnQuY29tMSAwHgYDVQQDExdEaWdpQ2VydCBHbG9iYWwgUm9vdCBH
MjAeFw0xMzA4MDExMjAwMDBaFw0zODAxMTUxMjAwMDBaMGExCzAJBgNVBAYTAlVT
MRUwEwYDVQQKEwxEaWdpQ2VydCBJbmMxGTAXBgNVBAsTEHd3dy5kaWdpY2VydC5j
b20xIDAeBgNVBAMTF0RpZ2lDZXJ0IEdsb2JhbCBSb290IEcyMIIBIjANBgkqhkiG
9w0BAQEFAAOCAQ8AMIIBCgKCAQEAuzfNNNx7a8myaJCtSnX/RrohCgiN9RlUyfuI
2/Ou8jqJkTx65qsGGmvPrC3oXgkkRLpimn7Wo6h+4FR1IAWsULecYxpsMNzaHxmx
1x7e/dfgy5SDN67sH0NO3Xss0r0upS/kqbitOtSZpLYl6ZtrAGCSYP9PIUkY92eQ
q2EGnI/yuum06ZIya7XzV+hdG82MHauVBJVJ8zUtluNJbd134/tJS7SsVQepj5Wz
tCO7TG1F8PapspUwtP1MVYwnSlcUfIKdzXOS0xZKBgyMUNGPHgm+F6HmIcr9g+UQ
vIOlCsRnKPZzFBQ9RnbDhxSJITRNrw9FDKZJobq7nMWxM4MphQIDAQABo0IwQDAP
BgNVHRMBAf8EBTADAQH/MA4GA1UdDwEB/wQEAwIBhjAdBgNVHQ4EFgQUTiJUIBiV
5uNu5g/6+rkS7QYXjzkwDQYJKoZIhvcNAQELBQADggEBAGBnKJRvDkhj6zHd6mcY
1Yl9PMWLSn/pvtsrF9+wX3N3KjITOYFnQoQj8kVnNeyIv/iPsGEMNKSuIEyExtv4
NeF22d+mQrvHRAiGfzZ0JFrabA0UWTW98kndth/Jsw1HKj2ZL7tcu7XUIOGZX1NG
Fdtom/DzMNU+MeKNhJ7jitralj41E6Vf8PlwUHBHQRFXGU7Aj64GxJUTFy8bJZ91
8rGOmaFvE7FBcf6IKshPECBV1/MUReXgRPTqh5Uykw7+U0b6LJ3/iyK5S9kJRaTe
pLiaWN0bfVKfjllDiIGknibVb63dDcY3fe0Dkhvld1927jyNxF1WW6LZZm6zNTfl
MrY=
-----END CERTIFICATE-----

Note	You can also download this certificate here: https://www.digicert.com/kb/digicert-root-certificates.htm#roots

• Verify that the PEM import is successful. A message is displayed after importing the certificate.

enable
configure terminal
parameter-map type umbrella global
	token AABBA59A0BDE1485C912AFE472952641001EEECC
		
exit

From Cisco IOS XE 17.15.1a, you can use scope API keys to configure DNS security, using the use-v2-api command. To continue using legacy keys, use the no use-v2-api command.

For devices running with Cisco IOS XE 17.15.1a and higher releases, the use-v2-api command does not need to be explicitly configured. The no use-v2-api command must be configured on devices running with Cisco IOS XE 17.15.1a and higher releases, when legacy credentials are used.

To configure Cisco Umbrella Connector using scope API keys:

Import the root certificate of DigiCert given below into the device:

-----BEGIN CERTIFICATE-----
MIIFazCCA1OgAwIBAgIRAIIQz7DSQONZRGPgu2OCiwAwDQYJKoZIhvcNAQELBQAw
TzELMAkGA1UEBhMCVVMxKTAnBgNVBAoTIEludGVybmV0IFNlY3VyaXR5IFJlc2Vh
cmNoIEdyb3VwMRUwEwYDVQQDEwxJU1JHIFJvb3QgWDEwHhcNMTUwNjA0MTEwNDM4
WhcNMzUwNjA0MTEwNDM4WjBPMQswCQYDVQQGEwJVUzEpMCcGA1UEChMgSW50ZXJu
ZXQgU2VjdXJpdHkgUmVzZWFyY2ggR3JvdXAxFTATBgNVBAMTDElTUkcgUm9vdCBY
MTCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoCggIBAK3oJHP0FDfzm54rVygc
h77ct984kIxuPOZXoHj3dcKi/vVqbvYATyjb3miGbESTtrFj/RQSa78f0uoxmyF+
0TM8ukj13Xnfs7j/EvEhmkvBioZxaUpmZmyPfjxwv60pIgbz5MDmgK7iS4+3mX6U
A5/TR5d8mUgjU+g4rk8Kb4Mu0UlXjIB0ttov0DiNewNwIRt18jA8+o+u3dpjq+sW
T8KOEUt+zwvo/7V3LvSye0rgTBIlDHCNAymg4VMk7BPZ7hm/ELNKjD+Jo2FR3qyH
B5T0Y3HsLuJvW5iB4YlcNHlsdu87kGJ55tukmi8mxdAQ4Q7e2RCOFvu396j3x+UC
B5iPNgiV5+I3lg02dZ77DnKxHZu8A/lJBdiB3QW0KtZB6awBdpUKD9jf1b0SHzUv
KBds0pjBqAlkd25HN7rOrFleaJ1/ctaJxQZBKT5ZPt0m9STJEadao0xAH0ahmbWn
OlFuhjuefXKnEgV4We0+UXgVCwOPjdAvBbI+e0ocS3MFEvzG6uBQE3xDk3SzynTn
jh8BCNAw1FtxNrQHusEwMFxIt4I7mKZ9YIqioymCzLq9gwQbooMDQaHWBfEbwrbw
qHyGO0aoSCqI3Haadr8faqU9GY/rOPNk3sgrDQoo//fb4hVC1CLQJ13hef4Y53CI
rU7m2Ys6xt0nUW7/vGT1M0NPAgMBAAGjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNV
HRMBAf8EBTADAQH/MB0GA1UdDgQWBBR5tFnme7bl5AFzgAiIyBpY9umbbjANBgkq
hkiG9w0BAQsFAAOCAgEAVR9YqbyyqFDQDLHYGmkgJykIrGF1XIpu+ILlaS/V9lZL
ubhzEFnTIZd+50xx+7LSYK05qAvqFyFWhfFQDlnrzuBZ6brJFe+GnY+EgPbk6ZGQ
3BebYhtF8GaV0nxvwuo77x/Py9auJ/GpsMiu/X1+mvoiBOv/2X/qkSsisRcOj/KK
NFtY2PwByVS5uCbMiogziUwthDyC3+6WVwW6LLv3xLfHTjuCvjHIInNzktHCgKQ5
ORAzI4JMPJ+GslWYHb4phowim57iaztXOoJwTdwJx4nLCgdNbOhdjsnvzqvHu7Ur
TkXWStAmzOVyyghqpZXjFaH3pO3JLF+l+/+sKAIuvtd7u+Nxe5AW0wdeRlN8NwdC
jNPElpzVmbUq4JUagEiuTDkHzsxHpFKVK7q4+63SM1N95R1NbdWhscdCb+ZAJzVc
oyi3B43njTOQ5yOf+1CceWxG1bQVs5ZufpsMljq4Ui0/1lvh+wjChP4kqKOJ2qxq
4RgqsahDYVvTH9w7jXbyLeiNdd8XM2w9U/t7y0Ff/9yi0GE44Za4rF2LN9d11TPA
mRGunUHBcnWEvgJBQl9nJEiU0Zsnvgc/ubhPgXRR4Xq37Z0j4r7g1SgEEzwxA57d
emyPxgcYxn/eR44/KJ4EBs+lVDR3veyJm+kXQ99b21/+jh5Xos1AnX5iItreGCc=
-----END CERTIFICATE-----

Note	You can also download this certificate here: https://letsencrypt.org/certs/isrgrootx1.pem

Note	It is recommended to use the scope API keys for Umbrella configuration. Support for legacy keys will be deprecated.

The following example provides the configurations for DNS security with API keys:

parameter-map type umbrella global
api-key <api-key>
orgid <org-id>
secret 0 <secret>
dnscrypt
vrf 1
dns-resolver umbrella

To register the Cisco Umbrella tag, perform these steps:

1. Configure the umbrella parameter map as shown in the previous section.

2. Configure umbrella out on the WAN interface:

   interface gigabitEthernet 0/0/1
    umbrella out 

3. Configure umbrella in on the LAN interface:

   interface gigabitEthernet 0/0/0.4
    umbrella in mydevice_tag 

   Note	For the Cisco devices, the length of the hostname and umbrella tag should not exceed 49 characters.

4. After you configure umbrella in with a tag using the umbrella in mydevice_tag command, the device registers the tag to the Cisco Umbrella Integration portal.

5. The device initiates the registration process by resolving api.opendns.com. You need to have a name server (ip name-server x.x.x.x) and domain lookup (ip domain-lookup) configured on the device to successfully resolve the FQDN.

   Note	You should configure the umbrella out command before you configure umbrella in command. Registration is successful only when the port 443 is in open state and allows the traffic to pass through the existing firewall.

You can identify the traffic to be bypassed using domain names. In the Cisco device, you can define these domains in the form of regular expressions. If the DNS query that is intercepted by the device matches one of the configured regular expressions, then the query is bypassed to the specified DNS server without redirecting to the Cisco Umbrella cloud. This sample configuration shows how to define a regex parameter-map with a desired domain name and regular expressions:

Device# configure terminal
Device(config)# parameter-map type regex dns_bypass
Device(config)# pattern www.fisco.com
Device(config)# pattern .*engineering.fisco.* 

Attach the regex param-map with the openDNS global configuration as shown below:

Device(config)# parameter-map type umbrella global
Device(config-profile)# token AADDD5FF6E510B28921A20C9B98EEEFF 
Device(config-profile)# local-domain dns_bypass

• DNSCrypt

• Resover IP

• Public-Key

We recommend that you change the above parameters only when you perform certain tests in the lab. These parameters are reserved for future use. If you modify these parameters, it can affect the normal functioning of the device.

Resolver

The following commands change the redirection of DNS packets from the Cisco device to Cisco Umbrella cloud:

• resolver ipv4 1.1.1.1

• resolver ipv4 1.1.1.2

• resolver ipv6 1234::1

• resolver ipv6 2345::1

In this example, all the IPv4 DNS packets are redirected to 1.1.1.1 or 1.1.1.2 and IPv6 DNS packets are redirected to 1234::1 or 2345::1. You should remove the IP address to restore to the default values of the resolver. When you modify a resolver IP address, the following message is displayed:

User configured would overwrite defaults
Defaults are restored when no more user configured are present

With the default values of 208.67.222.222 and 208.67.220.220, all DNS packets are redirected to Cisco Umbrella Anycast resolvers. The device uses the first default resolver IP address for all its redirection. When the Cisco device does not receive a response for three consecutive DNS queries, the device automatically switches to a different resolver IP address. This behavior remains the same for IPv6 resolver addresses.

Note	IPv6 redirection is deferred and all IPV6 DNS packets are not redirected to Cisco Umbrella Anycast servers.

Verify the Cisco Umbrella Connector configuration using the following commands:

Router# show umbrella config
Umbrella Configuration                                                             
==================                                                           
   Token:  AAC1A2555C11B2B798FFF3AF27C2FB8F001CB7B2 
   OrganizationID: 1882034                                 
   Local Domain Regex parameter-map name: NONE                                     
   DNSCrypt: Enabled                                                               
   Public-key: B735:1140:206F:225D:3E2B:D822:D7FD:691E:A1C3:3CC8:D666:8D0C:BE04:BFAB:CA43:FB79                                                                        
   UDP Timeout: 5 seconds                                                          
   Resolver address:                                                               
       1. 208.67.220.220                                                           
       2. 208.67.222.222                                                           
       3. 2620:119:53::53                                                          
       4. 2620:119:35::35                                                          
   Umbrella Interface Config:
       Number of interfaces with "opendns out" config: 1
         1. GigabitEthernet0/0/0                        
             Mode     :  OUT                            
             VRF      : global(Id: 0)                   
       Number of interfaces with "opendns in" config: 1 
         1. GigabitEthernet0/0/1                        
             Mode      : IN                              
             Tag       : test                            
             Device-id : 010a6aef0b443f0f
             VRF       : global(Id: 0)

Device# show umbrella deviceid
Device registration details
Interface Name          Tag       Status   Device-id
GigabitEthernet0/0/1     guest  200 SUCCESS 010a7ba73bd216d1


Device#show umbrella dnscrypt
    DNSCrypt: Enabled
Public-key: B735:1140:206F:225D:3E2B:D822:D7FD:691E:A1C3:3CC8:D666:8D0C:BE04:BFAB:CA43:FB79
Certificate Update Status:
Last Successful Attempt : 10:55:40 UTC Apr 14 2016
Last Failed Attempt : 10:55:10 UTC Apr 14 2016
Certificate Details:
Certificate Magic : DNSC
Major Version : 0x0001
Minor Version : 0x0000
Query Magic : 0x717744506545635A
Serial Number : 1435874751
Start Time : 1435874751 (22:05:51 UTC Jul 2 2015)
End Time : 1467410751 (22:05:51 UTC Jul 1 2016)
Server Public Key :
ABA1:F000:D394:8045:672D:73E0:EAE6:F181:19D0:2A62:3791:EFAD:B04E:40B7:B6F9:C40B
Client Secret Key Hash :
BBC3:409F:5CB5:C3F3:06BD:A385:78DA:4CED:62BC:3985:1C41:BCCE:1342:DF13:B71E:F4CF
Client Public key :
ECE2:8295:2157:6797:6BE2:C563:A5A9:C5FC:C20D:ADAF:EB3C:A1A2:C09A:40AD:CAEA:FF76
NM key Hash :
F9C2:2C2C:330A:1972:D484:4DD8:8E5C:71FF:6775:53A7:0344:5484:B78D:01B1:B938:E884

Troubleshoot issues that are related to enabling Cisco Umbrella Integration feature using these commands:

• debug umbrella device-registration

• debug umbrella config

• debug umbrella dnscrypt

Depending on the OS, run either of these two commands from the client device:

• The nslookup -type=txt debug.umbrella.com command from the command prompt of the Windows machine

• The nslookup -type=txt debug.umbrella.com command from the terminal window or shell of the Linux machine

nslookup -type=txt debug.opendns.com 8.8.8.8
Server: 8.8.8.8
Address: 8.8.8.8#53
Non-authoritative answer:
debug.opendns.com text = "server r6.mum1"
debug.opendns.com text = "device 010A826AAABB6C3D"
debug.opendns.com text = "organization id 1892929"
debug.opendns.com text = "remoteip 171.168.1.7"
debug.opendns.com text = "flags 436 0 6040 39FF000000000000000"
debug.opendns.com text = "originid 119211936"
debug.opendns.com text = "orgid 1892929"
debug.opendns.com text = "orgflags 3"
debug.opendns.com text = "actype 0"
debug.opendns.com text = "bundle 365396"
debug.opendns.com text = "source 72.163.220.18:36914"
debug.opendns.com text = "dnscrypt enabled (713156774457306E)"

This example shows how to enable Cisco Umbrella Integration: