Simplify DNS Policy Management With New Umbrella Tagging APIs

This weblog submit will present you how one can automate DNS coverage administration with Tags.
To streamline DNS coverage administration for roaming computer systems, categorize them utilizing tags. By assigning a normal tag to a group of roaming computer systems, they are often collectively addressed as a single entity throughout coverage configuration. This strategy is really useful for deployments with many roaming computer systems, starting from a whole lot to hundreds, because it considerably simplifies and quickens coverage creation.

High-level workflow description

1. Add API Key
2. Generate OAuth 2.0 entry token
3. Create tag
4. Get the checklist of roaming computer systems and establish associated ‘originId’
5. Add tag to gadgets.

The Umbrella API offers a normal REST interface and helps the OAuth 2.0 consumer credentials stream. While creating the API Key, you possibly can set the associated Scope and Expire Date.

To begin working with tagging, it is advisable to create an API key with the Deployment learn/write scope.

After producing the API Client and API secret, you need to use it for associated API calls.

First, we have to generate an OAuth 2.0 entry token.

You can do that with the next Python script:

import requests
import os
import json
import base64

api_client = os.getenv('API_CLIENT')
api_secret = os.getenv('API_SECRET')

def generateToken():

   url = "https://api.umbrella.com/auth/v2/token"

   usrAPIClientSecret = api_client + ":" + api_secret
   primaryUmbrella = base64.b64encode(usrAPIClientSecret.encode()).decode()
   HTTP_Request_header = {"Authorization": "Basic %s" % primaryUmbrella,
"Content-Type": "utility/json;"}

   payload = json.dumps({
   "grant_type": "client_credentials"
   })

   response = requests.request("GET", url, headers=HTTP_Request_header, knowledge=payload)
   print(response.textual content)
   access_token = response.json()['access_token']
   print(entryToken)

   return entryToken


if __name__ == "__main__":
   entryToken = generateToken()

Expected output:
{“token_type”:”bearer”,”access_token”:”cmVwb3J0cy51dGlsaXRpZXM6cmVhZCBsImtpZCI6IjcyNmI5MGUzLWQ1MjYtNGMzZS1iN2QzLTllYjA5NWU2ZWRlOSIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJ1bWJyZWxsYS1hdXRoei9hdXRoc3ZjIiwic…OiJhZG1pbi5wYXNzd29yZHJlc2V0OndyaXRlIGFkbWluLnJvbGVzOnJlYWQgYWRtaW4udXNlcnM6d3JpdGUgYWRtaW4udXNlcnM6cmVhZCByZXBvcnRzLmdyYW51bGFyZXZlbnRzOnJlYWQgyZXBvcnRzLmFnZ3Jl…MzlL”,”expires_in”:3600}

We will use the OAuth 2.0 entry token retrieved within the earlier step for the next API requests.

Let’s create tag with the title “Windows 10”

def addTag(tagName):
   url = "https://api.umbrella.com/deployments/v2/tags"

   payload = json.dumps({
   "title": tagName
   })

   headers = {
   'Accept': 'utility/json',
   'Content-Type': 'utility/json',
   'Authorization': 'Bearer ' + entryToken
   }

   response = requests.request("POST", url, headers=headers, knowledge=payload)

   print(response.textual content)


addTag("Windows 10", accesToken)

Expected output:

{
   "id": 90289,
   "organizationId": 7944991,
   "title": "Windows 10",
   "originsModifiedAt": "",
   "createdAt": "2024-03-08T21:51:05Z",
   "modifiedAt": "2024-03-08T21:51:05Z"
}

Umbrella dashboard, List of roaming computer systems with out tags 

Each tag has its distinctive ID, so we should always observe these numbers to be used within the following question.

The following operate helps us Get the List of roaming computer systems:

def getListRoamingComputers(accesToken):

url = "https://api.umbrella.com/deployments/v2/roamingcomputers"

payload = {}
headers = {
'Accept': 'utility/json',
'Content-Type': 'utility/json',
'Authorization': 'Bearer ' + entryToken
}

response = requests.request("GET", url, headers=headers, knowledge=payload)

print(response.textual content)

Expected output:

[
{
“originId”: 621783439,
“deviceId”: “010172DCA0204CDD”,
“type”: “anyconnect”,
“status”: “Off”,
“lastSyncStatus”: “Encrypted”,
“lastSync”: “2024-02-26T15:50:55.000Z”,
“appliedBundle”: 13338557,
“version”: “5.0.2075”,
“osVersion”: “Microsoft Windows NT 10.0.18362.0”,
“osVersionName”: “Windows 10”,
“name”: “CLT1”,
“hasIpBlocking”: false
},
{
“originId”: 623192385,
“deviceId”: “0101920E8BE1F3AD”,
“type”: “anyconnect”,
“status”: “Off”,
“lastSyncStatus”: “Encrypted”,
“lastSync”: “2024-03-07T15:20:39.000Z”,
“version”: “5.1.1”,
“osVersion”: “Microsoft Windows NT 10.0.19045.0”,
“osVersionName”: “Windows 10”,
“name”: “DESKTOP-84BV9V6”,
“hasIpBlocking”: false,
“appliedBundle”: null
}
]

Users can iterate by means of the JSON checklist objects and filter them by osVersionName, title, deviceId, and so on., and document the associated originId within the checklist that we are going to use to use the associated tag.

With associated tag ID and roaming computer systems originId checklist, we will lastly add a tag to gadgets, utilizing the next operate:

def addTagToUnits(tagId, machineList, accesToken):
   url = "https://api.umbrella.com/deployments/v2/tags/{}/devices".format(tagId)

   payload = json.dumps({
   "addOrigins":
   })
   headers = {
   'Accept': 'utility/json',
   'Content-Type': 'utility/json',
   'Authorization': 'Bearer ' + entryToken
   }

   response = requests.request("POST", url, headers=headers, knowledge=payload)

   print(response.textual content)

addTagToUnits(tagId, [ 621783439, 623192385 ], accesToken)

Expected output:

{
   "tagId": 90289,
   "addOrigins": [
       621783439,
       623192385
   ],
   "removeOrigins": []
}

After including tags, let’s test the dashboard

Umbrella dashboard, checklist of roaming computer systems after we add tags utilizing API

A associated tag is obtainable to pick when creating a brand new DNS coverage.

Notes:

• Each roaming pc will be configured with a number of tags
• A tag can’t be utilized to a roaming pc on the time of roaming consumer set up.
• You can not delete a tag. Instead, take away a tag from a roaming pc.
• Tags will be as much as 40 characters lengthy.
• You can add as much as 500 gadgets to a tag (per request).

Try these updates within the DevNet Sandbox

Give it a attempt! Play with these updates utilizing the Umbrella DevNet Sandbox.

Share: