Overview


BastionZero is entirely built with an API first philosophy. Everything that a user can do in the b() web app is available via an API. This enables organizations to drive their own business logic programmatically, with little need for an administrator to manually update b() as operations and management requirements change or to retrieve specific logs or events regarding a particular user, target, or API key.


The entire b() API can be viewed at BastionZero API


In this KBA we will demonstrate how the API can be used with Postman. At the conclusion of the article a user will have a working Postman configuration as well as the understanding on how to utilize the API programmatically.


B() Configuration


The first step in utilizing the b() API is generating an API key. The API key is used to authenticate your API call to the service for your organization. The API key name is used in the b() audit logs so you may want to choose a key that clearly identifies an intent for that key. In this case we've chosen an API key that indicates it is used for this KBA demonstration. Lastly, remember that API keys are credentials. You should always protect your API keys by restricting access, deleting keys no longer in use, creating keys for different integrations, & using the b() logging service to monitor your API use for inconsistencies and anomalies. Never embed your API keys directly in apps or secret files. Always use a key vault!


Without further comment let's move onto configuration. The first step is to generate the API key. You'll need to give it a unique name and use the copy feature to save away your client ID and client secret before closing the modal. 


Go to Create -> API Key 


Once you provided the API key name you will see the modal above. Again, remember to capture your API keys which can be done using the copy icon to the right of your keys. You may list all the API keys generated on your platform by going to:


System Controls -> Integrations - API keys 




This completes creating and naming an API key that can be used to make API calls.


Postman Configuration


Postman is an easy to use API tool that will allow one to test the configuration and set up of the BastionZero API. If you haven't already done so, please review the postman documentation and install the tool from the following URL, installing postman.


Create Global Variables


The first thing to do is to set up your client secret as a global environment variable. This makes it easy to reuse in your API calls as you set them up in your Postman collection. This is accomplished by selecting the 'Eye' in the upper right of the Postman UI, then Edit in the Globals section of the modal landing you in the variable edit modal. Next, add a new variable and paste your secrets into the initial value column. Below we used 'client_secret' and 'client_id' as our variables.  We will use these in our API postman setup. 



Integrate with the b() API


We will next create an API request to list all targets. Click the '+' icon in the same row  as the eye icon.  Postman will open an 'untitled request' to which we will insert the appropriate information:



Visit https://cloud.bastionzero.com/api. Search for 'ssm/list' and notice it is a post command. The body of the request list some optional schema, which in this case includes dynamic targets. If you didn't wish to include dynamic targets you could include this scheme and change the value to false.


The steps to defining the API are as follows:

  1. Change the HTTP method a GET to a POST in the drop down
  2. Type 'https://cloud.bastionzero.com/api/v1/ssm/list' as the URL
  3. Select the Headers tab
    1. Add 'X-API-KEY' as your header key with the value being your client secret variable. Below mine is {{client_secret}}
    2. Add 'content-type' as another key with the value being 'application/json'
  4. Switch to the Body tab
    1. Select 'Raw' in the drop down box with JSON as being the format (if it does not default)
    2. On line 1 add '{ }' for the body of the request


Your postman should look very similar to the screen shots below when completed:




Don't forgot to name your API and save it in a collection! Once you've verified the above go ahead and hit send. You should receive a JSON list of all your targets, similar to below:



The b() log will show the API key was used to make an API request per the following user event:



If your API call failed check the following:

  1. Make sure your API secret is valid by associating the API key name with your API key list.
  2. Re-check your Postman configuration. Typical errors include forgetting the API body or making sure the Auth tab has 'no auth' set in the configuration type.

Summary

In this KBA we used b() API keys and Postman to configure and test a b() API to list all SSM targets. We generated an API key pair and referenced the b() Swagger API page containing the full API listing as part of the service.


We used the client secret and swagger information to configure postman to list all SSM targets. We ran the method to illustrate  the setup working end to end and saw the API return a JSON list of our SSM targets.