Umbrella Network Tunnels API: create an IPsec tunnel

Network Tunnels

The Umbrella Network Tunnels API enables you to provision tunnels and view details about your network tunnels.

You can also:

List the Umbrella data centers
Delete a tunnel
Update credentials for a tunnel
Find information about tunnels in your organization
Find policy information for a tunnel
Get tunnel state information

Create a Network Tunnel

POST /organizations/{organizationId}/tunnels

Request Body Fields

Name	Type	Description
name	string	Human-readable name to give the tunnel. Required
siteOriginId	integer	Site origin ID to associate with the tunnel.
deviceType	string	The device type from which the tunnel originates. The default value is "other". For more information about valid types, see Network Device Types.
serviceType	string	The Service type to associate with the tunnel. The default is "SIG". Valid values are SIG or Private Access.
networkCIDRs	array	Enter IPv4 ranges and CIDR addresses. For `serviceType` "SIG" - add all public and private address ranges used internally by your organization. Overrides Umbrella's default behavior, which allows traffic destined for RFC-1918 addresses to return through the tunnel. If `serviceType` is "Private Access" this field is required, otherwise optional. 0.0.0.0/0 is not allowed.
transport	object	Tunnel transport object. For more information, see Tunnel Transport Object.
authentication	object	For more information see Authentication Object.

Network Device Types

ASA
FTD
ISR
Meraki MX
Viptela cEdge
Viptela vEdge
other

Tunnel Transport Object

Name	Type	Description
protocol	string	Tunnel transport protocol. The default is IPsec.

Authentication Object

Name	Type	Description
type	string	The authentication method. The default is PSK.
parameters	object	For more information, see Parameters Object.

Parameters Object

Name	Type	Description
idPrefix	string	A human-readable ID for the tunnel, used to generate the ID portion of the Pre-Shared Key (PSK). If omitted, ID will be generated and provided in response. Tunnels with a Device Type of ASA must provide an IP address string for this field. Tunnels with a Device Type of "other" may use either an IP address or a human-readable string. PSK IDs will not be automatically generated for ASA devices.
secret	string	The secret portion of a Pre-Shared Key (PSK). If omitted, a secret will be generated and provided in the response (16-64 characters, at least 1 upper and lowercase letter, 1 numeral, no special characters).

Request

curl -i -X POST "https://management.api.umbrella.com/v1/organizations/{organizationId}/tunnels" \
-H 'Authorization: Basic %YourEncodedKeySecret%' \
-H 'Content-Type: application/json' \
-d '{
    "name": "string",
    "deviceType": "ASA",
    "siteOriginId": 123456,
    "serviceType": "SIG",
    "networkCIDRs": [
        "123.111.222.25/24",
        "111.222.39.1/32"
    ],
    "transport": {
        "protocol": "IPSec"
    },
    "authentication": {
        "type": "PSK",
        "parameters": {}
    }
}'

Response

Sample response (200, OK):

{
  "id": 1122321,
  "uri": "/organization/2345432/tunnels/1122321",
  "name": "Site01Tunnel",
  "siteOriginId": 123456,
  "client": {
    "deviceType": "ASA",
    "authentication": {
      "type": "PSK",
      "parameters": {
        "id": "admin@2561066-237952254-umbrella.com",
        "modifiedAt": "2018-06-13T16:07:07.222Z",
        "secret": "This123Secret"
      }
    }
  },
  "transport": {
    "protocol": "IPSec"
  },
  "serviceType": "SIG",
  "networkCIDRs": [
    "123.111.222.25/24",
    "111.222.39.1/32"
  ],
  "meta": {
    "networkId": 0
  },
  "createdAt": "2018-06-13T16:07:07.222Z",
  "modifiedAt": "2018-06-13T16:07:07.222Z"
}

Update Network Tunnel

Update an IPsec tunnel in Umbrella.

PUT /organizations/{organizationId}/tunnels/{id}

Request Body Fields

Name	Type	Description
name	string	The display name given to the tunnel. The name cannot exceed 50 characters in length and cannot have any special characters other than spaces and hyphens. Required
siteOriginId	integer	Site Origin ID to associate with the tunnel.
networkCIDRs	array	Enter IPv4 ranges and CIDR addresses. For `serviceType` "SIG" - add all public and private address ranges used internally by your organization. Overrides Umbrella's default behavior, which allows traffic destined for RFC-1918 addresses to return through the tunnel. If `serviceType` is "Private Access" this field is required, otherwise optional. 0.0.0.0/0 is not allowed.
client	object	Configuration metadata of the client. For more information, see Client Object. Required

Client Object

Name	Type	Description
deviceType	string	The type of device from which to establish the tunnel. For more information, see Network Device Types.
authentication	object	The authentication context of the client. For more information, see Authentication Object.

Network Device Types

ASA
FTD
ISR
Meraki MX
Viptela cEdge
Viptela vEdge
other

Authentication Object

Name	Type	Description
type	string	The authentication method. The default is PSK.
parameters	object	For more information, see Parameters Object.

Parameters Object

Name	Type	Description
id	string	The PSK ID. If an IP address is used as the ID, the IP address itself is returned.
modifiedAt	string	The date and time when the tunnel was modified.

Request

curl -i -X PUT "https://management.api.umbrella.com/v1/organizations/{organizationId}/tunnels/{id}" \
-H 'Authorization: Basic %YourEncodedKeySecret%' \
-H 'Content-Type: application/json' \
-d '{
    "name": "Site01Tunnel",
    "siteOriginId": 123456,
    "networkCIDRs": [
        "123.111.222.25/24",
        "111.222.39.1/32"
    ],
    "client": {
        "deviceType": "ASA",
        "authentication": {
            "type": "PSK",
            "parameters": {
                "id": "admin@2561066-237952254-umbrella.com",
                "modifiedAt": "2018-06-13T16:07:07.222Z"
            }
        }
    }
}'

Response

Sample response (200, OK):

{
  "id": 1122321,
  "uri": "/organization/2345432/tunnels/1122321",
  "name": "Site01Tunnel",
  "siteOriginId": 123456,
  "client": {
    "deviceType": "ASA",
    "authentication": {
      "type": "PSK",
      "parameters": {
        "id": "admin@2561066-237952254-umbrella.com",
        "modifiedAt": "2018-06-13T16:07:07.222Z",
        "secret": "This123Secret"
      }
    }
  },
  "transport": {
    "protocol": "IPSec"
  },
  "serviceType": "SIG",
  "networkCIDRs": [
    "123.111.222.25/24",
    "111.222.39.1/32"
  ],
  "meta": {
    "networkId": 0
  },
  "createdAt": "2018-06-13T16:07:07.222Z",
  "modifiedAt": "2018-06-13T16:07:07.222Z"
}

Get Network Tunnels

List the tunnels for the organization.

GET /organizations/{organizationId}/tunnels

Request Query Parameters

For this endpoint, you can set four optional query parameters:

filters
includeState
limit
startKey

Name	Type	Description
filters	string	Filters the collection by device type, service type, status, or data center. For example {"name":"test","deviceType":"ISR","serviceType":"SIG","status":"UP","dataCenter":"pao1.edc"}.
includeState	string	A boolean value (true or false). If set to true, response includes the tunnel state information.
limit	integer	Set the number of records to return in the collection. If unset, Umbrella returns all tunnels in the organization.
startKey	string	Select the offset into the tunnel collection. If unset, Umbrella returns the first tunnel in the collection. If you set the `limit` field and there are more records to read in the collection, then Umbrella returns the `startKey` value in the hypermedia link header.

Request

curl -i GET "https://management.api.umbrella.com/v1/organizations/{organizationId}/tunnels" \
-H 'Authorization: Basic %YourEncodedKeySecret%' \
-H 'Content-Type: application/json'

Response

Sample response (200, OK):

[
    {
        "id": 1122321,
        "uri": "/organization/2345432/tunnels/1122321",
        "name": "Site01Tunnel",
        "siteOriginId": 123456,
        "client": {
                "deviceType": "ASA",
                "authentication": {
                    "type": "PSK",
                    "parameters": {
                        "id": "admin@2561066-237952254-umbrella.com",
                        "modifiedAt": "2018-06-13T16:07:07.222Z"
                    }
                }
        },
        "transport": {
            "protocol": "IPSec"
        },
        "serviceType": "SIG",
        "networkCIDRs": [
            "123.111.222.25/24",
            "111.222.39.1/32"
        ],
        "meta": {
            "networkId": 12345
        },
        "createdAt": "2018-06-13T16:07:07.222Z",
        "modifiedAt": "2018-06-13T16:07:07.222Z"
    }
]

List Tunnel State Information

List the tunnel state information.

GET /organizations/{organizationId}/tunnelsState

Request

curl -i GET "https://management.api.umbrella.com/v1/organizations/{organizationId}/tunnelsState" \
-H 'Authorization: Basic %YourEncodedKeySecret%' \
-H 'Content-Type: application/json'

Response

Click to view the sample response (200, OK)


[
    {
        "tunnelId": "163367136",
        "status": "UP",
        "dc": "chi1.edc",
        "dcName": "Equinix Chicago",
        "ikeState": "ESTABLISHED",
        "ipsecState": "INSTALLED",
        "peerId": "unique-value@1234567-234567812-umbrella.com",
        "peerIp": "198.18.195.1",
        "localIp": "198.25.43.19",
        "peerPort": "4500",
        "ike": {
          "age": "6194",
          "dhGroup": "MODP_2048",
          "prfAlgo": "PRF_HMAC_SHA1",
          "encAlgo": "AES_CBC",
          "initiatorSpi": "cf065c564a511834",
          "responderSpi": "a3cd5c8533c80069"
        },
        "ipsec": {
          "age": "6194",
          "integrityAlgo": "HMAC_SHA1_96",
          "encAlgo": "NULL",
          "encKeySize": "128",
          "spiIn": "c6ef7503",
          "spiOut": "00010102",
          "peerSelectors": [
            "0.0.0.0/0"
          ]
        },
        "data": {
          "packetsIn": "10",
          "bytesIn": "1000",
          "idleTimeIn": "100",
          "packetsOut": "10",
          "bytesOut": "1000",
          "idleTimeOut": "100",
          "initialized": "2023-10-19T22:15:12.765623734Z"
        },
        "modifiedAt": "2018-06-13T16:07:07.222Z"
    }
]

Get Data Centers

List the information about the IPsec-enabled data centers. The data center information includes the IP address and location details.

GET /service/tunnel/datacenters

Request

curl -i GET "https://management.api.umbrella.com/v1/service/tunnel/datacenters" \
-H 'Authorization: Basic %YourEncodedKeySecret%' \
-H 'Content-Type: application/json'

Response

Click to view the sample response (200, OK)

{
    "continents": [
        {
            "cities": [
                {
                    "dc": "fra1.edc",
                    "fqdn": "eu1-b.vpn.sig.umbrella.com",
                    "latitude": "50.121212",
                    "longitude": "8.6365638",
                    "name": "Frankfurt",
                    "range": "146.112.96.8/32"
                },
                {
                    "dc": "lon1.edc",
                    "fqdn": "eu1-a.vpn.sig.umbrella.com",
                    "latitude": "51.5286416",
                    "longitude": "-0.1015987",
                    "name": "London",
                    "range": "146.112.97.8/32"
                },
                {
                    "dc": "mil1.edc",
                    "latitude": "45.464211",
                    "longitude": "9.191383",
                    "name": "Milan",
                    "range": "146.112.107.8/32"
                },
                {
                    "dc": "prg1.edc",
                    "fqdn": "eu2-b.vpn.sig.umbrella.com",
                    "latitude": "50.08804",
                    "longitude": "14.42076",
                    "name": "Prague",
                    "range": "146.112.103.8/32"
                },
                {
                    "dc": "cdg1.edc",
                    "fqdn": "eu2-a.vpn.sig.umbrella.com",
                    "latitude": "48.8588589",
                    "longitude": "2.3470599",
                    "name": "Paris",
                    "range": "146.112.102.8/32"
                },
                {
                    "dc": "cph1.edc",
                    "latitude": "55.6712674",
                    "longitude": "12.5608388",
                    "name": "Copenhagen",
                    "range": "146.112.100.8/32"
                },
                {
                    "dc": "sto1.edc",
                    "latitude": "59.33258",
                    "longitude": "18.0649",
                    "name": "Stockholm",
                    "range": "146.112.101.8/32"
                },
                {
                    "dc": "mad1.edc",
                    "latitude": "-3.716667",
                    "longitude": "40.416667",
                    "name": "Madrid",
                    "range": "146.112.106.8/32"
                },
                {
                    "dc": "mrs1.edc",
                    "latitude": "43.339359",
                    "longitude": "5.347080",
                    "name": "Marseille",
                    "range": "146.112.120.2/32"
                }
            ],
            "name": "Europe"
        },
        {
            "cities": [
                {
                    "dc": "nrt1.edc",
                    "fqdn": "as1-b.vpn.sig.umbrella.com",
                    "latitude": "35.6178560",
                    "longitude": "139.7473840",
                    "name": "Tokyo",
                    "range": "146.112.112.8/32"
                },
                {
                    "dc": "sin1.edc",
                    "fqdn": "as1-a.vpn.sig.umbrella.com",
                    "latitude": "1.3185848",
                    "longitude": "103.8455665",
                    "name": "Singapore",
                    "range": "146.112.113.8/32"
                },
                {
                    "dc": "hkg1.edc",
                    "latitude": "22.3700556",
                    "longitude": "114.1535941",
                    "name": "Hong Kong",
                    "range": "146.112.114.8/32"
                },
                {
                    "dc": "mum1.edc",
                    "latitude": "19.0728300",
                    "longitude": "72.8826100",
                    "name": "Mumbai",
                    "range": "146.112.117.8/32"
                }
            ],
            "name": "Asia"
        },
        {
            "cities": [
                {
                    "dc": "mel1.edc",
                    "fqdn": "au1-b.vpn.sig.umbrella.com",
                    "latitude": "-37.814",
                    "longitude": "144.96332",
                    "name": "Melbourne",
                    "range": "146.112.119.8/32"
                },
                {
                    "dc": "syd1.edc",
                    "fqdn": "au1-a.vpn.sig.umbrella.com",
                    "latitude": "-33.7969235",
                    "longitude": "150.9224326",
                    "name": "Sydney",
                    "range": "146.112.118.8/32"
                }
            ],
            "name": "Australia"
        },
        {
            "cities": [
                {
                    "dc": "ash1.edc",
                    "fqdn": "us2-b.vpn.sig.umbrella.com",
                    "latitude": "39.0299604",
                    "longitude": "-77.4771231",
                    "name": "Ashburn",
                    "range": "146.112.82.8/32"
                },
                {
                    "dc": "atl1.edc",
                    "latitude": "33.755",
                    "longitude": "-84.39",
                    "name": "Atlanta",
                    "range": "146.112.85.8/32"
                },
                {
                    "dc": "lax1.edc",
                    "fqdn": "us1-a.vpn.sig.umbrella.com",
                    "latitude": "34.0204989",
                    "longitude": "-118.4117325",
                    "name": "Los Angeles",
                    "range": "146.112.67.8/32"
                },
                {
                    "dc": "mia1.edc",
                    "latitude": "25.782324",
                    "longitude": "-80.2310801",
                    "name": "Miami",
                    "range": "146.112.84.8/32"
                },
                {
                    "dc": "pao1.edc",
                    "fqdn": "us1-b.vpn.sig.umbrella.com",
                    "latitude": "37.4400648",
                    "longitude": "-122.1406715",
                    "name": "Santa Clara",
                    "range": "146.112.66.8/32"
                },
                {
                    "dc": "nyc1.edc",
                    "fqdn": "us2-a.vpn.sig.umbrella.com",
                    "latitude": "40.6893768",
                    "longitude": "-74.0442737",
                    "name": "New York",
                    "range": "146.112.83.8/32"
                },
                {
                    "dc": "yyz1.edc",
                    "fqdn": "ca1-a.vpn.sig.umbrella.com",
                    "latitude": "43.7182713",
                    "longitude": "-79.3777061",
                    "name": "Toronto",
                    "range": "146.112.65.8/32"
                },
                {
                    "dc": "yvr1.edc",
                    "fqdn": "ca1-b.vpn.sig.umbrella.com",
                    "latitude": "49.2873150",
                    "longitude": "-123.1192930",
                    "name": "Vancouver",
                    "range": "146.112.64.8/32"
                },
                {
                    "dc": "mex1.edc",
                    "latitude": "20.583333",
                    "longitude": "-100.383333",
                    "name": "Queretaro",
                    "range": "146.112.94.8/32"
                },
                {
                    "dc": "rst1.edc",
                    "latitude": "38.95872",
                    "longitude": "-77.358606",
                    "name": "Reston",
                    "range": "146.112.86.2/32"
                },
                {
                    "dc": "den1.edc",
                    "latitude": "39.742043",
                    "longitude": "-104.991531",
                    "name": "Denver",
                    "range": "146.112.73.2/32"
                }
            ],
            "name": "North America"
        },
        {
            "cities": [
                {
                    "dc": "rio1.edc",
                    "latitude": "-22.908333",
                    "longitude": "43.196388",
                    "name": "Rio de Janeiro",
                    "range": "146.112.93.8/32"
                },
                {
                    "dc": "sao1.edc",
                    "latitude": "-23.550520",
                    "longitude": "-46.633309",
                    "name": "Sao Paulo",
                    "range": "146.112.92.8/32"
                }
            ],
            "name": "South America"
        },
        {
            "cities": [
                {
                    "dc": "cpt1.edc",
                    "latitude": "-33.925278",
                    "longitude": "18.423889",
                    "name": "Cape Town",
                    "range": "146.122.109.8/32"
                },
                {
                    "dc": "jnb1.edc",
                    "latitude": "-26.204103",
                    "longitude": "28.047305",
                    "name": "Johannesburg",
                    "range": "146.112.108.8/32"
                }
            ],
            "name": "Africa"
        }
    ]
}

Data Centers Response Table

Data Centers
Continent	City	DC	FQDN	Latitude	Longitude	Range
Europe
	Frankfurt	fra1.edc	eu1-b.vpn.sig.umbrella.com	50.121212	8.6365638	146.112.96.8/32
	London	lon1.edc	eu1-a.vpn.sig.umbrella.com	51.5286416	-0.1015987	146.112.97.8/32
	Milan	mil1.edc		45.464211	9.191383	146.112.107.8/32
	Prague	prg1.edc	eu2-b.vpn.sig.umbrella.com	50.08804	14.42076	146.112.103.8/32
	Paris	cdg1.edc	eu2-a.vpn.sig.umbrella.com	48.8588589	2.3470599	146.112.102.8/32
	Copenhagen	cph1.edc		55.6712674	12.5608388	146.112.100.8/32
	Stockholm	sto1.edc		59.33258	18.0649	146.112.101.8/32
	Madrid	mad1.edc		-3.716667	40.416667	146.112.106.8/32
	Marseille	mrs1.edc		43.339359	5.347080	146.112.120.2/32
Asia
	Tokyo	nrt1.edc	as1-b.vpn.sig.umbrella.com	35.6178560	139.7473840	146.112.112.8/32
	Singapore	sin1.edc	as1-a.vpn.sig.umbrella.com	1.3185848	103.8455665	146.112.113.8/32
	Hong Kong	hkg1.edc		22.3700556	114.1535941	146.112.114.8/32
	Mumbai	mum1.edc		19.0728300	72.8826100	146.112.117.8/32
Australia
	Melbourne	mel1.edc	au1-b.vpn.sig.umbrella.com	-37.814	144.96332	146.112.119.8/32
	Sydney	syd1.edc	au1-a.vpn.sig.umbrella.com	-33.7969235	150.9224326	146.112.118.8/32
North America
	Ashburn	ash1.edc	us2-b.vpn.sig.umbrella.com	39.0299604	-77.4771231	146.112.82.8/32
	Atlanta	atl1.edc		33.755	-84.39	146.112.85.8/32
	Los Angeles	lax1.edc	us1-a.vpn.sig.umbrella.com	34.0204989	-118.4117325	146.112.67.8/32
	Miami	mia1.edc		25.782324	-80.2310801	146.112.84.8/32
	Santa Clara	pao1.edc	us1-b.vpn.sig.umbrella.com	37.4400648	-122.1406715	146.112.66.8/32
	New York	nyc1.edc	us2-a.vpn.sig.umbrella.com	40.6893768	-74.0442737	146.112.83.8/32
	Toronto	yyz1.edc	ca1-a.vpn.sig.umbrella.com	43.7182713	-79.3777061	146.112.65.8/32
	Vancouver	yvr1.edc	ca1-b.vpn.sig.umbrella.com	49.2873150	-123.1192930	146.112.64.8/32
	Queretaro	mex1.edc		20.583333	-100.383333	146.112.94.8/32
	Reston	rst1.edc		38.95872	-77.358606	146.112.86.2/32
	Denver	den1.edc		39.742043	-104.991531	146.112.73.2/32
South America
	Rio de Janeiro	rio1.edc		-22.908333	43.196388	146.112.93.8/32
	Sao Paulo	sao1.edc		-23.550520	-46.633309	146.112.92.8/32
Africa
	Cape Town	cpt1.edc		-33.925278	18.423889	146.122.109.8/32
	Johannesburg	jnb1.edc		-26.204103	28.047305	146.112.108.8/32

Try It Out

We provide sample scripts that you can use to build integrations with the Umbrella Network Tunnels API. The Umbrella Network Tunnels code samples are found in the Cisco Cloud Security GitHub repository (https://github.com/CiscoDevNet/cloud-security). For more information, see Cisco Cloud Security Network Tunnel Deployment Samples.