Migrate from Legacy API to modern API for Secure Access and Umbrella DNS Redirection on Network Devices

At the time of writing there is no official documentation from Cisco on how to integrate this via. the API keys and secrets, therefor this post places a intermediate documentation for myself and customers which are starting on Cisco Secure Access or migrating their tenants from Umbrella to Secure Access and leverages the DNS Redirection integration on their IOS XE platforms.

This integration is possible via a range of Cisco products, I’m focusing on the traditional devices running IOS XE in this article. I may create one specific for WLCs at a later point in time as well, which currently has the legacy API documentation. But same principles for authentication applies

Introduction

By integrating the network devices with Cisco Umbrella or the successor, Cisco Secure Access, it enables the devices to inspect the DNS query that is sent to any DNS server through the network and acts as a DNS forwarder which transparently intercepts the DNS requests and redirects all queries to Cisco Umbrella/Secure Access for full control and granular policy enforcement.

DNScrypt between the network device and Umbrella or Secure Access is also possible via. this integration, ultimately encrypting the DNS packet between the edge and Cisco.

Adding on top of that it gives the possibility to append “Extended” DNS (EDNS) information from the device and into the Cisco portal. This further enhances security efficacy by including information such as local client IP and device information. This makes for a greater and more in-depth logging capabilities and brings flexibility to enforce policies by network device or per network device interface (e.g. tagging GigabitEthernet2 as INTERNAL and GigabitEthernet3 as GUEST with different DNS policies) - regardless of the WAN IP egress and its policies.

Getting Started

In this post I’ll not be covering all the details and configurational parameters available when using the network devices as DNS redirectors, but I’ll go through how you setup the authentication API keys within the portal(s), how to configure them on the IOS XE devices and an example of how to configure two interfaces with different tags for policy enforcement.

Create an API key in Umbrella / Secure Access

Cisco Umbrella

Navigate to Admin > API Keys - the rest is exactly the same as in the Secure Access section.

Cisco Secure Access

Navigate to Admin > Management > API Keys

Select the API Keys section (not KeyAdmin Keys)

Click the Add button in the top right corner and be sure to select the Deployments > Network Devices with a Read / Write permission. No other permissions is necessary for this key.

Be sure to note down the Key Secret as this is only shown once, unless you rotate the keys, which makes the previous secret obsolete - API key is of course also necessary to note down, both keys we’ll be using on our network device for registration.

Configuration of Network Device (IOS XE)

In this case I’m demonstrating this on a CSR1000v, but most of the IOS XE 16.6+ hardware should be able to support this - consult the datasheets for the specifics (C8000v excluded)

Importing the root certificate to establish HTTPS connection

At this pont we need to import the root certificate in order to establish a trust between the portal and network device.

We’ve two possibilities for importing this.

1. Import the whole list of bundled trusted CAs provided by Cisco in IOS.p7b file (used by other Cisco products as well)
2. Import only the Secure Access certificate

Import bundle via IOS.p7b

crypto pki trustpool import url http://www.cisco.com/security/pki/trs/ios.p7b

Verify import

show crypto pki trustpool

Verify the specific Cisco Secure Access Root CA

show crypto pki trustpool | b Cisco Secure Access Root CA

Import the specific Cisco Secure Access Root CA

crypto pki trustpool import terminal

-----BEGIN CERTIFICATE-----
MIIDXTCCAkWgAwIBAgIJBwkXMb4xT8NhMA0GCSqGSIb3DQEBCwUAMEsxEzARBgNV
BAsTCkhvcm9sb2dpdW0xDjAMBgNVBAoTBUNpc2NvMSQwIgYDVQQDExtDaXNjbyBT
ZWN1cmUgQWNjZXNzIFJvb3QgQ0EwIBcNMjMwODIzMTkwOTM3WhgPMjA5OTA4MjMx
OTA5MzdaMEsxEzARBgNVBAsTCkhvcm9sb2dpdW0xDjAMBgNVBAoTBUNpc2NvMSQw
IgYDVQQDExtDaXNjbyBTZWN1cmUgQWNjZXNzIFJvb3QgQ0EwggEiMA0GCSqGSIb3
DQEBAQUAA4IBDwAwggEKAoIBAQDDuQZlUA6TDiymDG3l4Cda9APmnIkw/v2KPJ8k
XpnVlhjCKUflPS1TDzN3b0aCyJ7AP/YAJby6eUfyZJDXClcHQysR/JutE3cz8Y6v
Q/oZnHsjM5Iy86QrBj+/xK5xIGoZYBcsOea3VBVy5WS/Kh7VodgMw6I6bgRib1El
MBVmejUKf+sv1ZeanTPNFHaHFxGR/umLSMnHXSY0RQs+MwV+7mLfMojmz5MSu/Kt
gYomWC15WHWZ6gCEJ9Gjv/ad6b+4Jz7imarQEsXfEXnTanBGBYxuw2yeL/mPQT/d
S5kjZZd2IO0A44ouyx8Vp9Xd+M3+0q4FgWjA5aq/PWL0ZcaTAgMBAAGjQjBAMA4G
A1UdDwEB/wQEAwIBBjAPBgNVHRMBAf8EBTADAQH/MB0GA1UdDgQWBBR7DuUB7EDt
HYojI9fVglT7SY9YZTANBgkqhkiG9w0BAQsFAAOCAQEAp52wM0XCzkj0IU01JyTA
03YRYmZ0w1mq7ILdf6NdTn/X/8hHAHAxggvOQHM/YBTosX1v/B4bA7Gxc+igdPVb
34mzw/nHgNGxbRXGGkU93QD+Q2i3W4ocrFMLQzw9POFlL90+KdMsXiexcKd3n9Ns
cZx3GT0xQhNK0bnCrRvkR/pBo96FuqC2yd619IoJu9nI6vBKiWZJYPBU9aDDG5dR
6/e9UNCLnS0zSPtEK1E1vpML0v8iQ+YDvlp6IQE37FYHSFwB8oswRpMpZBeyntNZ
Rs4h/L6jYuseDPQzlHg4nZoN8hdVQCHTZaWwFFo6SFfduXvF0kRCag0CGnfhVbOIlg==
-----END CERTIFICATE-----

Verify the import of Cisco Secure Access Root CA

show crypto pki trustpool | b Cisco Secure Access Root CA

Setting up the connector and parameter-map

Next we’ll be setting up the global parameter-map to connect our network device(s) to Umbrella/Secure Access, in my example I’ve included the feature to use DNScrypt for encrypted DNS and adding the possibility to use EDNS for more visibility in my logs (local client IP for instance)

Originally with the legacy token based authentication only the “token” command was necessary.

parameter-map type umbrella global
 dnscrypt 
 udp-timeout 5
 api-key <YOUR API KEY>
 orgid <YOUR ORG ID>
 secret 0 <YOUR API SECRET>

The settings should be pretty self explaining.

Retrieving your orgID is pretty simple - look at the URL of your Umbrella or Secure Access to identify your specific ID.

Umbrella - 1234567 is your ID

https://dashboard.umbrella.com/o/1234567/

Secure Access - Standalone dashboard - 1234567 is your ID

https://dashboard.sse.cisco.com/org/1234567/

Secure Access - Security Cloud Control dashboard - 1234567 is your ID

https://security.cisco.com/secure-access/org/1234567

Your parameter-map should look something like this once all data is collected.

parameter-map type umbrella global
 dnscrypt 
 udp-timeout 5
 api-key dbd5[…]5f12
 orgid 1234567
 secret 0 fd44[…]2614

Setup network tags for interfaces

We need to define the interfaces and their respective tags to be used as policy enforcement or classification of networks.

We’ll be needing one OUT interface which ultimately is the egress point from our device onto the WAN. In my example this is GigabitEthernet1

interface GigabitEthernet1
 ip address 192.168.51.5 255.255.255.0
 ip nat outside
 umbrella out

Now we’ll be defining two different tags where our clients come from and assign them different policies.

INTERNAL for tagging our internal interface

interface GigabitEthernet2
 ip address 192.168.10.1 255.255.255.0
 ip nat inside
 umbrella in INTERNAL

GUEST for tagging our guest interface

interface GigabitEthernet3
ip address 192.168.20.1 255.255.255.0
ip nat inside
umbrella in GUEST

Verify connectivity and device creation

The following commands can be used to verify from the network device side if things are configured and registered successfully (HTTP code 201 means success created)

show umbrella deviceid
Interface Name          Tag              Status          Device-id 
GigabitEthernet2        INTERNAL         201 CREATED     f338586ab63beca0
GigabitEthernet3        GUEST            201 CREATED     f338b43c7fc8b1d1

Confirm the tags has been propagated to the control plane in FP layer.

show platform software umbrella f0 interface-info
InterfaceID         Name      Mode     DeviceID        Tag 
---------------------------------------------------------------
 05      GigabitEthernet1     OUT                      
 06      GigabitEthernet2      IN    f338586ab63beca0  INTERNAL
 07      GigabitEthernet3      IN    f338b43c7fc8b1d1  GUEST

In Umbrella / Secure Access you should now be able to see the network and respective tags has been created under the Network Devices section

Secure Access: Resources > Network Devices

Umbrella: Deployments > Network Devices

Picture below is from Secure Access and we can see that both my Gi2 and Gi3 interfaces with different tags is online and has received data from the network device.

Policy enforcement and connection event

Once we’ve the network devices registered with their tags we can now use them in our access control policy for granular enforcement per tag.

In my case I’ve created two very simple policies which is both allowing all internet, but they’re two district policy sets matching on different network device tags - so I could block certain sites only on one of them at a time.

Once a DNS query is sent from the client on either the internal or guest network the DNS is intercepted by the network device and forwarded to Cisco Secure Access and enforced by the policy defined for that tag - in this case its coming from the Gi3 (GUEST tag) and matching the guest policy from above.

Notice how we also fetch the local RFC1918 client IP through the EDNS information as well. Normally only fetched by using the Umbrella Roaming Module or Virtual Appliance DNS.

This is regardless of the configured DNS server to be used on the client - as seen below its actually not configured to be using Cisco DNS in any sense, but rather Cloudflare at 1.1.1.1

References

For further information and the specifics about troubleshooting and additional parameter options, visit the official integration guide below - keep in mind this only reflects the legacy API token, but rest of configuration is still the same, only authentication method has changed.

Security Configuration Guide: Cisco Umbrella Integration On Cisco 4000 Series ISRs