Cisco Umbrella for Government Network Tunnel Groups and Regions API

Network Tunnel Groups and Regions API

The Cisco Umbrella for Government Network Tunnel Groups and Regions API enables you to programmatically manage Network Tunnel Group resources. You can get the collection of network tunnel groups in the organization. You can also create, edit, view and delete a network tunnel group, get the status of the network tunnel group, and get the state information for the tunnels in the network tunnel groups. You can find the Network Tunnel Groups and Regions API endpoints under the deployments scope.

Once you create a network tunnel group and establish a network tunnel from a supported network device, Umbrella associates the IPsec tunnel with the network tunnel group. Make an API request to the Network Tunnel Groups API to get the status information for the tunnels in the organization's network tunnel groups and monitor the state of the tunnels.

Network Tunnel Groups are deployed with hubs, which are located in data centers. When you add a Network Tunnel Group, Umbrella creates primary and secondary hubs. Umbrella associates each hub with a different regional data center. A Network Tunnel Group and the tunnels in the group share a primary and secondary hub.

Hubs support network tunnel redundancy and enable high-availability of the tunnels for the organization. Each hub in a network tunnel group can connect to multiple tunnels.

Note: A hub that is configured for NAT can support up to 100 IPsec tunnels. Otherwise, a hub supports 0–10 tunnels.

Overview

IPsec Tunnels and Supported Network Devices

When network devices establish an IPsec tunnel to Umbrella, the network tunnel joins the associated network tunnel group by providing the credentials that were used to create the network tunnel group.

Umbrella supports creating IPsec tunnels in network tunnel groups for these network devices:

  • ASA
  • FTD
  • ISR
  • Meraki MX
  • Viptela cEdge (Catalyst SD-WAN)
  • Viptela vEdge (Catalyst SD-WAN)
  • other

How to Create a Network Tunnel Group

  1. Make a Network Tunnel Groups and Regions API request to create a Network Tunnel Group. For more information, see Create Network Tunnel Group. Once the tunnel group is deployed, the initial state of the tunnel group changes from Unestablished to Inactive.
  2. Next, configure a tunnel on the network device. Use the attributes that you selected to deploy the network tunnel group to associate the tunnel to the tunnel group. The network tunnel group requires certain attributes to enable the connection of the tunnel with IPsec IKEv2 on the network device. For more information, see Data for Creating the Network Tunnel Group.

After you create the network tunnel group and tunnel, you can enable end user devices (roaming computers) to connect securely and send traffic to Umbrella. Once Umbrella receives and logs traffic from a network tunnel, the tunnel state is considered Active. For information about roaming computers, see List Roaming Computers.

For information about creating an API request with curl, see Request and Response Samples: Create Network Tunnel Group.

For information about making API requests to the Network Tunnel Groups resources from a Python script, see Network Tunnel Groups API Guide.

Rate Limits for Network Tunnel Groups and Regions

Umbrella enables rate limits on the Network Tunnel Groups and Regions API endpoints. For more information, see Rate Limits > Network Tunnel Groups and Regions.

Data for Creating the Network Tunnel Group

To add a network tunnel group in the organization, create a JSON object with the required fields and send an API request (POST) with the data in the API request body.

Note: The name of the network tunnel group must be unique for all network tunnel groups in the organization.

Field Name JSON Schema Type Description Example
name (Required) string A label for the network tunnel group.
The value of name is a sequence of 1–50 alphanumeric, space, and hyphen (-) characters.		 network tunnel group-one
region (Required) string The name of the region that is used to get the primary and secondary data centers for the hubs. us-gov-east-1
passphrase (Required) string The pass phrase for the primary and secondary tunnels.
The value of passphrase is a sequence of 16–64 alphanumeric characters.
passphrase must contain at least one upper and one lowercase letter as well as one numeral.
passphrase may not include special characters.		 t3stingTunn3lNow
authIdPrefix (Required) oneOf (AuthId Prefix) An IP address or ID for the network tunnel. The value of authIdPrefix is used to generate the ID portion of the Pre-Shared Key (PSK).
deviceType (Optional) string The type of device that can establish the network tunnel. The default value is other.
Valid values are: ASA, FTD, ISR, Meraki MX, Viptela cEdge, Viptela vEdge, or other.		 ASA
routing (Optional) object (Routing) The routing information for the network tunnel.
The nat routing type is used when the tunnels in your organization connect to network spaces with overlapping IP address spaces.

AuthId Prefix

Field Name JSON Schema Type Description Example
authIdPrefix string The value of authIdPrefix is a sequence of 8–100 alphanumeric, period (.), underscore(_), and dash(-) characters.
array (string) The value of authIdPrefix is a list of IP addresses. You must include at least two IP addresses.

Routing

The routing information for the network tunnel. The nat routing type is used when the tunnels in your organization connect to network spaces with overlapping IP address spaces.

  • If the routing type is nat, then set the data field to null or an empty string.
  • If the routing type is bgp, then set the data field with the asNumber field.
  • If the routing type is static, then set the data field with the networkCIDRs field.
Field Name JSON Schema Type Description Example
type (Required) string The type of the route. Valid values are: bgp, nat, or static. bgp
data (Required) oneOf (Network CIDRs or AS Number) The list of network CIDR addresses or the autonomous system (AS) number. 5600

Network CIDRs

Field Name JSON Schema Type Description Example
networkCidrs (Required) array (string) The public and private address ranges used internally by your organization. CIDR blocks must be unique for all network tunnel groups in the organization. Only required for the static routing type. 123.111.222.25/24

AS Number

Field Name JSON Schema Type Description Example
asNumber (Required) string The border gateway protocol (BGP) autonomous system (AS) number for private access network tunnels. Only required for the bgp routing type. Any other routing types except bgp are ignored. Specify an integer between 0–65536. 9004

Troubleshooting

Umbrella returns an error for various conditions including creating a network tunnel group with a name or CIDR block that is already associated with another network tunnel group in the organization.

Creating a Network Tunnel Group With Static Routing and Invalid CIDR Block

{
    "error": "Validation Error",
    "requestId": "84fcbe53-c973-4fc0-aaac-f615edcc87e5",
    "validationErrors": {
        "routing": "Static routing data must contain valid RFC 4632 CIDR ranges"
    }
}

Creating a Network Tunnel Group With Duplicate CIDR Address

{
    "error": "Network tunnel group CIDR must be unique in an organization",
    "requestId": "ebb12b25-fb19-4717-b219-b13bf07d3e85"
}

Network Tunnel Groups and Regions API Endpoints