Configuring Altair Client

This article describes how to configure Altair for multiple environments, and how to run a pre-execution script to authenticate against VMware Aria’s GraphQL API if required. Altair can be downloaded as a desktop application, or installed as a browser plugin - these steps work for all versions.

Create an Environment

Altair uses Environments to store global variables that can be accessed using the {{variable-name}} syntax. We will use an Environment to store configuration (the Aria User Token and FQDN) as well as programatically storing variables (the authentication header and expiry date). This allows you to write queries that can be re-used in different environments by incorporating the variables.

Create an Environment for each Aria Organization you wish to access:

1. Click on the Environment select drop down (top right)
2. Click “Environments”, then “Add Environment”
3. Add JSON to create the ARIA_USER_TOKEN variable, with your CSP User Token scoped to Aria Hub
4. Add JSON to create the ARIA_FQDN variable (e.g. api.mgmt.cloud.vmware.com)
5. Name and save the environment

Create a Collection

A collection is a grouping of saved queries that can inherit some of the same settings. For example, we will create a “pre-execution” script to authenticate against the GraphQL API - this will run before the execution of any GraphQL query in the Collection and ensure the API token is generated. Create a collection to hold all the Aria Hub requests and to provide a pre-request script to authenticate all calls.

Create a new request that will call the Authentication mutation and generate an access token. You can use this query to manually generate the Bearer token that is needed for the authorization header in each query.

1. Create a new query
2. Add the URL with the ARIA_FQDN variable https://{{ARIA_FQDN}}/aria/graphql
3. Add the authentication mutation to the query window

   mutation($ARIA_USER_TOKEN: String!) {
     authMutation {
       generateAccessToken(userToken: $ARIA_USER_TOKEN) {
         authorization
       }
     }
   }

4. Add a variable in the Variables pane (you might need to expand this pane). The variable’s value maps to the ARIA_USER_TOKEN environment variable:

   {
     "ARIA_USER_TOKEN": "{{ARIA_USER_TOKEN}}"
   }

5. Click the save icon, and select “Add to Collection” from the drop down menu
   

   

6. Name the request, and select “create an new collection”. Enter a name for the new collection
   

   

Once the Request is saved you can click “Send Request” to ensure the ARIA_FQDN and ARIA_USER_TOKEN variables are set correctly. The result should show 200 OK and the authorization Bearer token:

Create a Pre-request authentication script on the Collection

Altair allows you to execute a pre-request script on both a collection and a request itself - the collection one will execute first, followed by the request one. The Collection pre-request will apply to every Request in the Collection (if you tick the Enable pre-request script on the query).

1. Click the three dots on the Collection and open the Edit menu
   

   

2. Add the pre-request script (see below for code) to the Pre-request window and tick “Enable pre-request script”
   

   

3. Save the collection

The code block below has been commented to explain what it’s doing. The script will check for an existing authorization header and an expiry date/time for the existing header. It then compares the current date/time with the expiry to check if it’s already expired or still valid. If it’s valid, the script will return and the existing token will be used. If it’s expired, or if there is no value set (i.e. one does not exist) then the script will execute the authMutation to generate a new authorization header. Finally, the newly generated header will be saved to the current Environment along with the expiry date/time.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

// Get the current date/time
const dateNow = () => Date.now()
// Get the expiry date of the current access token, if it exists
const ARIA_ACCESS_TOKEN_EXPIRY = altair.helpers.getEnvironment("ARIA_ACCESS_TOKEN_EXPIRY") || 0;
// Get the authorization header, if it exists
const ARIA_AUTHORIZATION = altair.helpers.getEnvironment("ARIA_AUTHORIZATION") || 0;
// Get the user API token
const ARIA_USER_TOKEN = altair.helpers.getEnvironment("ARIA_USER_TOKEN")
 
// If there is no ARIA_AUTHORIZATION variable, or if the time now is later than the ARIA_ACCESS_TOKEN_EXPIRY value
if (ARIA_AUTHORIZATION == 0 || dateNow() >= Date.parse(ARIA_ACCESS_TOKEN_EXPIRY) ) {
  console.log("Access token expired, request a new one")
  // Execute the authorization mutation query and get a new access token and expiry date time
  const authResponse = await altair.helpers.request('POST', 'https://'+altair.helpers.getEnvironment('ARIA_FQDN')+'/aria/graphql',{ body: {"query":"mutation {\n  authMutation {\n    generateAccessToken(userToken: \""+ARIA_USER_TOKEN+"\") {\n      authorization\n      expirationTime\n    }\n  }\n}"} })
  // Set the Token Expiry and Authorization Environment Variables
  altair.helpers.setEnvironment("ARIA_ACCESS_TOKEN_EXPIRY", authResponse.data.authMutation.generateAccessToken.expirationTime, true)
  altair.helpers.setEnvironment("ARIA_AUTHORIZATION", authResponse.data.authMutation.generateAccessToken.authorization, true)
} else {
  // The current authorization header value is still valid
  console.log("Using existing ARIA_AUTHORIZATION")
}

Create new requests

With the Collection and pre-request script configured we can create a new request without having to authenticate each time.

1. Click “Add new” to create a new request and add the request URL if it’s not already populated https://{{ARIA_FQDN}}/aria/graphql
2. Create your query and any variables required
3. Click the “Set headers” icon (top left)
   
   
4. Add an Authorization header using the ARIA_AUTHORIZATION variable (this is created by the pre-request script and holds the Bearer token) and save. The variable may display as an error until the pre-request script is executed for the first time - this is expected.
   
   
5. Select the “Pre-request” tab and tick the “Enable pre-request script” - if you don’t enable it here, the Collection’s pre-request script will not execute! You do not need to add any script in the box (but you can, if desired, add scripts to execute after the Collection’s pre-request script)
   
   
6. Click on the save icon and “Add to Collection” (you must add to the Collection to inherit the pre-request script from the Collection)
   
   
7. Add to your Aria Hub collection and save

Now when you execute the query using the SEND REQUEST button, the pre-request script will execute the authorization mutation and create an environment variable for the bearer token and the timestamp for it’s expiry. That token will be re-used until it expires, when the authorization mutation will be used again. If you look at your environment variables again, you should now see the two additional variables, ARIA_ACCESS_TOKEN_EXPIRY and ARIA_AUTHORIZATION

Share this post