Authenticating With the API

Objective

To obtain an authentication token after logging in with the API, and use that token on subsequent API calls.

Authentication in the API

To use the API, you must have a valid user account on the Turbonomic instance. Also note that accounts can have different roles. The API will only execute commands that are valid for your user role. For example, to execute Turbonomic recommended actions, your account must have a role of either administrator, deployer, or automator.

To make API calls, you request an authentication token and pass it with each call to the Turbonomic API. The token request returns a cookie for your authentication. A common way to use this token is to store the cookie locally, and pass it with your API calls.

Example: curl -s -k -c /tmp/cookies -H 'accept: application/json' 'https://localhost/api/v3/login?hateoas=true' -d 'username=administrator&password=password'

Then, each request must use the -b cookie-filename parameter to use the session cookie delivered by the login request.

Another approach is to get the authentication header and parse out the authentication cookie. Then you can create a header for each API request that includes the cookie. For example, assume you store the value in a variable named token. You could use it like this:

headers = {'cookie': token}
r = requests.get('https://10.10.123.456/api/v3/targets/specs', headers=headers, verify=False, stream=True)

Prerequisites

In order to obtain an authentication token, you must have the following information:

The IP address of the Turbonomic instance.
The username and password of the user who will be logged in.

Procedure

To obtain an authentication token:

Construct the API payload.

The input body should be JSON, in the following format with your credentials in place of myUsername and myPassword:
```
{'username': 'myUsername', 'password': 'myPassword'}
                    
```
Make the API request.

Use the POST https://[INSTANCE_URL]/api/v3/login request, with the input body constructed in the previous step.

Retrieve the authentication token from the response headers.

Example headers:


{
  'Server':'nginx',
  'Date':'Mon, 01 Feb 2021 20:17:02 GMT',
  'Content-Type':'application/json',
  'Transfer-Encoding':'chunked',
  'Connection':'keep-alive',
  'Vary':'Accept-Encoding',
  'Set-Cookie':'JSESSIONID=node0jzerbqte09pe1j29x6ypo92fh17.node0; Path=/; HTTPOnly; Secure',
  'Expires':'Thu, 01 Jan 1970 00:00:00 GMT',
  'X-Content-Type-Options':'nosniff',
  'X-XSS-Protection':'1; mode=block',
  'Strict-Transport-Security':'max-age=63072000; includeSubDomains',
  'X-Frame-Options':'SAMEORIGIN',
  'X-Turbo-Upstream':'API',
  'Content-Encoding':'gzip'
}

The authentication token is the first ;-separated tocen in the value of the Set-Cookie header. In this example, it is JSESSIONID=node0jzerbqte09pe1j29x6ypo92fh17.node0.

Using the Authentication Token in Subsequent API Requests

Once you have obtained an authentication token, you can use that token to make further API requests. To do so, include a header in your request with the name of cookie and a value of the token. For example:


{'cookie': 'JSESSIONID=node0jzerbqte09pe1j29x6ypo92fh17.node0' }

Script Example

These listings show a function that gets the authentication token from the cookie, and a script that invokes the function and prints out the token value.

Function to get the token:

To invoke this function, pass the IP address, the username, and password as arguments. The function builds the authentication payload and requests the token from the given Turbonomic instance. It then parses out the first token in the Set-Cookie header and returns that value.

import json
import requests
import urllib3
urllib3.disable_warnings()

def get_cookie(ip, username, password):
	payload = {'username': username, 'password': password}
	r = requests.post(f'https://{ip}/api/v3/login', data=payload, verify=False)
	r.encoding = 'JSON'
	rh = r.headers
	token = rh['Set-Cookie'].split(';')[0]
	
	return token

Script that calls the function:

Assume the script is saved as use_login.py. Also assume the function is in the file ./login.py. To invoke this script, open a shell at the script file location and enter:

./use-login.py <My_IP_Address> <My_Username> <My_Pwd>

where the three arguments are the IP address of your Turbonomic, your username, and your password, respectively. The script imports the ./login.py file and checks for four arguments (the script name and the three arguments you passed). It then executes the login.get_cookie() function. The function returns a token, which the script then prints out.

#!/usr/bin/env python3

import sys
import login

if len(sys.argv) != 4:
	print("Incorrect arguments list.")
	sys.exit()
	
token = login.get_cookie(sys.argv[1], sys.argv[2], sys.argv[3])
print(f'TOKEN IS: {token}')

Script Result

The result of this script displays the authentication token:


TOKEN IS: JSESSIONID=node0jzerbqte09pe1j29x6ypo92fh17.node0