Cisco Secure Access Network Tunnel Groups and Regions API

Network Tunnel Groups and Regions

The Cisco Secure Access 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 Secure Access 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, Secure Access 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, Secure Access creates primary and secondary hubs. Secure Access 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
• How to Set the Filters Query Parameter with a JSON Object
• How to Create a Network Tunnel Group
• Rate Limits for Network Tunnel Groups and Regions
• Request Headers
• Data for Creating the Network Tunnel Group
• Troubleshooting
• Network Tunnel Groups and Regions API Endpoints

IPsec Tunnels and Supported Network Devices

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

Secure Access 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 Set the Filters Query Parameter with a JSON Object

Several Network Tunnel Groups and Regions API endpoints support query parameters. The /regions GET operation accepts the fields in the Region resource for the filters query parameter. The /networktunnelgroups GET operation accepts the fields in the Network Tunnel Group resource for the filters query parameter.

In this example, we describe the steps to set the filters query parameter with a JSON object on the /regions API request.

You can use the json.dumps method to serialize the JSON object as a string. Then, set the serialized string as the value of filters, and include the query parameter with the API request. For more information, see Network Tunnel Groups API Guide.

1. In Python, create a JSON object with the specific fields and values.

    data = {
        "peerIP": "25.123.22.10",
        "latitude": 39.0299604,
        "longitude": -77.4771231,
        "status": "available"
    }

2. Serialize the JSON object to a JSON-formatted string.

    json_filter_string = json.dumps(data)

3. Create a params variable set to an object with the filters field. Assign the value of the JSON-formatted string to the filters field.

        params = {
        "filters": json_filter_string
    }

4. Create the /regions API request and set the params variable for the query parameter.

    response = api.Query(deployments, regions_endpoint, GET, params)

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 Secure Access. Once Secure Access receives and logs traffic from a network tunnel, the tunnel state is considered Active. For information about roaming computers, see List Roaming Computers.

Rate Limits for Network Tunnel Groups and Regions

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

Request Headers

Unless specified, the Secure Access API endpoints use JSON for all requests and responses.

Note: For POST, PUT, and PATCH operations, set the HTTP Content-Type header to application/json in your API request.

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.

AuthId Prefix

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.

Network CIDRs

AS Number

Troubleshooting

Secure Access 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

• List Network Tunnel Groups
• Create Network Tunnel Group
• Get Network Tunnel Group
• Update Network Tunnel Group
• Delete Network Tunnel Group
• List Regions for Network Tunnel Groups
• Get State of Network Tunnel Group
• List State of Network Tunnel Groups
• Get Tunnel States for Peers
• Get Tunnel State