As a SteelCentral Controller user for SteelHead Mobile, also referred to as the Client Accelerator Controller, you may be asked to automate workflows such as generating custom end-point usage reports, configuring policies, and performing cluster maintenance. The Client Accelerator Controller provides a REST-based Application Programming Interface (API) so that you can develop these types of automation tools and integrate the Controller with your other systems.
This article is part one of a two-part series. In this article, you will learn: (1) how to enable your Controller for API usage, and (2) how to ‘login’ to the Controller API to obtain an OAuth token using a short Python example. The OAuth token is required to execute specific REST API commands.
Part two will present learning more about specific REST API commands and using the OAuth token.
Enable the REST API and Create an Access Code
The Controller provides online help that provides the necessary steps to initially enable the REST API and create an API access code. The access code is a credential in the same way your username-password is a credential. You use the access code to obtain an OAuth token, which is valid for one (1) hour, to execute specific REST API calls.
You can find help in this process directly in the Controller web UI as shown. The subsequent page then provides a link to online documentation. A short-cut to online help is here for quick access.
From the online Help page, select the ‘Configure Security Settings’ and then ‘Enabling REST API access’, as illustrated. A short-cut to this page is here for quick access.
Follow the steps to enable the API and create your API Access Code. On the Controller web UI, you can access the settings as shown.
When you complete the process, you will be presented with the Access Code value. The Access Code is a credential secret value. You should copy this value and store it in a secure system for later use by your automation tooling.
Python Example to Obtain OAuth Token
This next section presumes you are familiar with Python and installing packages from the PyPi repository system. A tutorial can be found here. Before you attempt to use this example code, you will need to set up a virtual environment and install the httpx package.
In a production environment, you would retrieve your access code from a secure system. In this example case, we will store it in a file called ‘access-code.txt’ to reduce complexity.
The purpose of the login function is to create a REST client using the httpx library and access code value to acquire an OAuth token. The login function will return the REST client with the token installed in the Authorization header area so it can be used for future calls to specific REST APIs.
Note on line 11 that the base_url value is assigned the Controller host URL. Any future REST command URLs need only to provide the specific API path without this base value. The verify=False parameter disables the SSL verification check against the Controller system.
Line 9 loads the Access Code value from the file called ‘access-code.txt’. This code presumes that the file exists in the directory where you are running this sample code.
Line 13 is where the Access Code value is used to obtain the OAuth token. A POST command is issued to the Controller REST API that will create the token. The token value returned is valid for one (1) hour only.
Line 19 checks the response to ensure there are no errors. If there are errors, such as an invalid access code, then an exception is raised to be handled by the calling code. An example exception is shown.
When the response contains a valid OAuth token, the response status_code will be 200. Lines 20-23 extract the new token from the response payload and store it into the client instance as the Authorization header value using the Bearer format.
At this point, the client instance can be used to execute specific Controller APIs. Part two of this blog will provide a step-by-step tutorial to use the token and create a user end-point report.
This article provided the information to get started using the Client Accelerator Controller API. Key highlights about the API:
- REST based API
- Uses OAuth and Bear Token authentication approach
- OAuth token is valid for one (1) hour only
- Online documentation is available directly from the Controller web UI
If you are interested in exploring existing open-source software libraries and examples, you can find the Riverbed open-source Github organization of repositories at https://github.com/riverbed
Please continue to part two in this series to learn more about using the Controller REST API. You will learn how to find more online documentation and create a User End-Points report with a short Python code example.