My Scripts To Try Out The Mist API

-

I recently spent some time looking at the Mist API after completing some of their online training to learn more about their service offering. I experimented with a few Python scripts I created to understand how I could retrieve information about my mini "free AP" network.

I dumped the scripts in to a GitHub repository so that others could take a look at them and either use them or analyze them and perhaps write scripts of their own.

I started writing a "ReadMe" page about the scripts and how to use them. The page soon grew to be a lot more detailed than I originally indended, but ended up containing many of the lessions I had learned when trying to figure out how to use the API with Python scripts.

You can see the full GitHub repository and the ReadMe at on my Git Hub site at : https://github.com/wifinigel/mist-utils

I've copy and pasted much of the content from the ReadMe below, as I thought it makes a pretty good blog article in its own right and there are probably many people who would never find it over on GitHub.

Checkout the full ReadMe page for more useful resources about Mist API information.


Usage

To use these scripts, you'll need to get your environment set up to run the scripts against your Mist network API.

You'll need to do the following steps (which are all detailed in this document):

  1. Get an API token
  2. Set you environment to use the token
  3. Install Python 3 (if you don't already have it)
  4. Download the scripts
  5. Test your environment works with the API
  6. Run the scripts

I'm assuming you have a Mist cloud dashboard account and an online AP or two to be able to perform the steps detailed in this document.

Mist API Overview

The Mist API allows you to perform a whole variety of operations on your organisation's Mist network instead of using their cloud dashboard.

This allows incredible flexibility if you would like to perform automation on your network.

The examples provided in this repository demonstrate how to pull data from the network to provide status and reporting information. The target audience I had in mind when writing these scripts is very much network engineers who would like to pull off infrastructure data to include in reports and documentation.

The scripts are written in Python as everyone tells me a I need to be able to code and Python is the flavour of the moment.

How Do We Pull Data Via An API ?

The API allows us to read, write, update and delete data on our network. We'll be primarily reading data, as that is the safest option when we're sending API requests in to our network. I'll leave you to explore writing, updating and deleting stuff yourself...I don't fancy being responsible for giving you tools that may damage your network (...yes I'm a coward like that).

To perform any sort of API operations, we need to send a http request to the API URL of the Mist cloud. You can think of this as being very similar to the operation we perform with a web browser when we pull pages from a web site. But, instead of using a browser, we use a Python script to send a https request, and, we get data back rather than a web page. The operations of a browser talking to a web page and a Python script pulling data from the Mist API site are outlined in the image below:

http_get_image

Authentication Token

When we use http to pull data with a Python script, we need to ensure that only authorized people can send requests to the API and retrieve our network data or potentially make configuration changes.

One way of authenticating any requests we send to the Mist API is to send our username and password with each request to verify our identity and that we are authorized to perform the request operation (such as getting a list of all APs on one of our network sites). However this is programmatically challenging and if the credentials are inadvertently revealed (e.g. they are seen by a third party), the may be easily recorded and used to provide unauthorized access.

A preferred method is to use an authentication token string. This is a very long randomised string of characters that cannot be remembered if seen and can be easily revoked and replace with a new token created if required. The token is used in place of username/password credentials when making requests to the API.

A token looks something like this:

    Nm3A2LkqTlgm8eDhnsZUjeJjdeuw6EAzvsoTgCYxtnkv51A2bcfjiGkAZB8QSgD3LCWeSzaHyeeyLFjouG6Ek7YroOcW1h

When a http request is set to a web server or API, a number of "headers" are sent with the request. These can contain a variety of data such as cookies and information about the web client (e.g. the browser type). When we are making an API call to the Mist cloud, we have to include the token as header in the format of :

  Authorization: Token Nm3A2LkqTlgm8eDhnsZUjeJjdeuw6EAzvsoTgCYxtnkv51A2bcfjiGkAZB8QSgD3LCWeSzaHyeeyLFjouG6Ek7YroOcW1h

(Note the handling of the token in headers is taken care of automatically in the scripts in this repo once you have created your own token, so don't worry too much about this detail.)

When the request is received by the mist API (at api.mist.com), it checks the token to see if it is valid and will then provide the appropriate access policy for that token. It will allow permissions such as read or write access, and will determine which organisations and sites may be accessed by the API call.

Getting an Authentication Token

To create a token to use with scripts that perform operations via the Mist API, we need to login to the Mist dashboard with our username and password.

Next, perform the following steps:

  1. Login to the Mist dashboard with a browser

  2. Open a new tab in your browser

  3. Enter the following URL in your browser: https://api.mist.com/api/v1/self/apitokens

  4. Assuming you are correctly logged in to your Mist site, you will see a page similar to this:

no_tokens_image

  1. This page shows us the token we have associated with our account. It should look like the image above (with an empty pair of square brackets in the upper highlighted area), assuming you have not created any token previously.

  2. Next we need to create a token by hitting the "Post" button highlighted in the image above. This will create a token for us.

  3. Now, we will see the token that as been generated for us. NOTE: You will only see this token once, so make sure you copy and paste it to somewhere safe. There is no way of retrieving a token later, the only option will to be generate a new token if you lose this one. The token field is shown in the image below. The value you need to save is the long string beginning 'CYbLfqGt' highlighted in the blue rectangle in the image below:

no_tokens_image

Using The Authentication Token

Now that we have an authentication token we can use it to provide authentication to the Mist cloud for our script operations.

The token created will be subject to the same access restrictions as our Mist dashboard account. For instance, if you do not have rights to delete APs with your dashboard login, your API token will also not be able to delete APs.

As the API token is a valuable set of credentials that could allow anyone who gets hold of it to access your network, it needs to be protected in the same way as any other credentials. Embedding the credentials in your script is probably not a great idea, as if you share it or it is accessed in some other way then your security is compromised.

A method that I like to use is to configure the token as an user-level environmental variable on the machine I am working on. This allows all of my scripts to access the token value, but it is only available to me. All of the scripts in this repo use this method. Therefore, you must set an environmental variable on your machine called MIST_TOKEN that contains the value of your token. All scripts will look for this value when they run - if it is not present, they will not run.

Setting the Env Var Token Value On A Mac

Temporarily setting the value in a terminal window:

  1. Open a terminal window
  2. Enter the command:
MIST_TOKEN="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
(where the xxxxx is replaced with your token string)
  1. Test it is set by executing the command (the configured token string should be shown):
echo $MIST_TOKEN

(Note, each time you close your terminal window, this will need to be repeated)

Permanently set the env var for all terminal windows you open:

  1. Open a terminal window
  2. Edit the file .profile using the Nano text editor:
nano .profile
  1. Add the following line at the bottom of the file
MIST_TOKEN="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
(where the xxxxx is replaced with your token string)
  1. Save the file using ctrl-x
  2. Close the terminal window and open a new one. Enter the following command to verify that the env var is set:
echo $MIST_TOKEN

Setting the Env Var Token Value On A Windows Machine

Temporarily setting the value in a command window:

  1. Open a command window (i.e. CMD)
  2. Enter the command:
set MIST_TOKEN="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
(where the xxxxx is replaced with your token string)
  1. Test it is set by executing the command (the configured token string should be shown):
echo %MIST_TOKEN%

(Note, each time you close your command window, this will need to be repeated)

Permanently set the env var for all command windows you open:

  1. Click on the Windows start button
  2. Type the word "environment"
  3. The option "Edit environment variables for your account" should appear in the search results - click on it
  4. In the "Environment Variables" panel that appears, we need to create an entry in the upper part of the panel in the user variables section.
  5. Hit the 'New' button and enter the env var details are shown below:

new_var_image

  1. Once this has been created, the MIST_TOKEN variable should be shown as in the image below:

env_vars_image

  1. Open a new command window (i.e. CMD)
  2. Check that the env var is available by typing the command:
echo %MIST_TOKEN%

(Note: this env var will always be available in every command window you open until you remove it from the environment variables panel)

Getting Python

You will need to have Python 3 installed on your machine to run the scripts in this repo. I cannot go through all of the steps required to do this, but you can get the Python software and installation instructions from : https://www.python.org/downloads/ (get the latest version of 3.x.x).

Once you have installed Python, open a terminal and command window and type the command "python -V" (that's capital 'V') to ensure it is correctly installed (note some platforms may require you to type "python3 -V"). This is a good confidence check that your good to go:

python_version_image

Getting The Scripts

There are 2 methods of getting the scripts in this repo:

  1. Use git (if you have it installed) using the command 'git clone https://github.com/wifinigel/mist-utils.git'

  2. Download a zip file of all the repo files and unzip them on your machine: https://github.com/wifinigel/mist-utils/archive/master.zip

Running The Scripts

Once you have downloaded the scripts, open a terminal or command windows and change directory to the folder you have created that contains the scripts.

Next, try running the 'check_env.py' script. This will check your environment and connectivity to the Mist cloud:

python check_env.py

check_env_image

If this passes all tests, you're good to go! I'll leave you to explore the other scripts yourself and hopefully create your own over time. Enjoy!!!

Popular posts from this blog

The 5GHz “Problem” For Wi-Fi Networks: DFS

-
Image
Wi-Fi networking provides us with 2 bands for the operation of wireless LAN networks: the 2.4Ghz band and the 5GHz band. The 2.4GHz band has a reputation of being something of a “sewer” of a band, due to its limited number of usable channels, the number of Wi-Fi devices already using the band, and the high levels of non-Wi-Fi interference that it experiences. Many wireless LAN professionals will generally advise that you put your “important stuff” on the 5GHz band whenever possible. 5GHz has far more channels available, a corresponding lower number of devices per channel, and generally suffers much lower non-Wi-Fi interference. However, beneath the headline of “2.4Ghz = bad, 5Ghz = good”, there lurks a shadowy figure that can be troublesome if you’re not aware of its potential impact: DFS. Background Wi-Fi networks operate in areas of RF spectrum that require no licence to operate. This is in contrast to many other areas of the radio spectrum that generally require some form of (p...
Read more

What Are Sticky Clients?

-
Image
One term you'll often hear banded about when talking with Wi-Fi professionals is "sticky clients". I thought it might be worth spending a few moments exploring what is meant by "sticky clients", why they are generally considered to be a bad thing in Wi-Fi networks and some approaches to mitigate them. Background Many folks dealing with Wi-Fi networks often talk about the "sticky" characteristics of wireless clients when discussing client roaming within a W-iFi network. In an ideal world, we'd like to have access points providing ubiquitous coverage across our desired area providing high-quality, consistent client coverage where-ever we go. In this wonderful land of rainbows and unicorns, our clients would gracefully roam from AP to AP, detecting and associating with their closest AP throughout the coverage area to ensure their best connection speed at all times. Unfortunately, the real world doesn’t quite reflect this roaming-client...
Read more

Microsoft NPS as a RADIUS Server for WiFi Networks: SSID Filtering

-
Image
The Microsoft Network Policy Server (NPS) is often used as a  RADIUS server for WiFi networks. It can provide authentication and authorization services for devices and users on a wireless network in a Windows Active Directory environment. In this article we look at how we can use NPS to provide authentication for WiFi users across a number of SSIDs. We have previously discussed how to authenticate groups of users using the same SSID and then assign them to a VLAN that is appropriate to their security authorization. However, there may still be instances where two or more SSIDs are in-use on a wireless network and we would like to base policy decisions on the SSID that the authentication request is being generated from. As an example, if we consider a school, perhaps we would like students to only be able to authenticate if they connected to the SSID: "Student_Net". Similarly,  staff should only be able to connect using the SSID: "Staff_Net". This would ...
Read more