CyberArk APIs Bruno

Bruno collection for CyberArk APIs
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgments

About The Project

This project was built to help developers get started with CyberArk APIs. It is a collection of APIs that can be used to interact with CyberArk's services when using the Bruno API client. The project is open source and contributions are welcome.

(back to top)

Getting Started

To get a local copy up and running follow these simple example steps.

Prerequisites

1. Install Bruno API client from https://www.usebruno.com/

Installation

1. Clone the repo

   git clone https://github.com/strick-j/CyberArk-APIs.git

2. Copy .env.example to .env and update the values. At a minimum the following values need to be set:

   # GENERAL SETTINGS
   TENANT_ID="21215455-1234-4123-8ab1-123a68520abc" # The GUID of your CyberArk ISPSS Tenant. You can find this when logged in via Tenant Details pop up available in the top right corner of the screen.
   IDENTITY_TENANT_ID="abc1234" # The ID of your CyberArk ISPSS Tenant. You can find this when logged in via Tenant Details pop up available in the top right corner of the screen.
   IDENTITY_TENANT_NAME="example" # The subdomain of your CyberArk ISPSS Tenant (e.g. in example.cyberark.com, this would be "example")
   IDENTITY_TENANT_SUFFIX="example.com" # The common suffix used for logging in to your CyberArk ISPSS Tenant
   
   PLATFORM_TOKEN_CLIENT_ID="user@example.com" # This is the username of the user you want to use to authenticate
   PLATFORM_TOKEN_CLIENT_SECRET="ExamplePasssword1234" # This is the password of the user you want to use to authenticate
   

3. Open the collection folder within Bruno.
4. Navigate to the desired API endpoint and change the environment to "local" in the top right corner of the Bruno GUI.
5. Run the API endpoint.

(back to top)

Usage

Within Bruno, you can navigate to the desired API endpoint and run the API. The collection is organized by CyberArk capibility and the endpoints leverage the variables in .env file to run the API.

Note: The various API endpoints are not yet fully implemented. This is a work in progress.

(back to top)

Usage: API Authentication

The various APIs require authentication. The authentication header for most of the endpoints is automatically generated using the "Pre Request" script in Bruno. The following is an example of the Pre Request Script for one of the API endpoints:

const platformTokenAuth = require('./tools/platformTokenAuth');

// Perform authentication usings platformToken.js tools
await platformTokenAuth.login();

In the example above, the Pre Request script specifically calls the platformTokenAuth.login() function. This function is defined in the platformTokenAuth.js file located in the tools folder. The platformTokenAuth.login() function is responsible for authenticating the user and generating the necessary headers for the API request.

For authentication to work properly you must set the appropriate values in the .env file. For example, if the endpoint is configured to use Platform Token authentication you must set the following values in the .env file:

PLATFORM_TOKEN_CLIENT_ID="user@example.com" 
PLATFORM_TOKEN_CLIENT_SECRET="ExamplePasssword1234"

If you are planning to use any of the SCIM endpoints you must set the following values in the .env file:

SCIM_CLIENT_ID="scim-client"
SCIM_CLIENT_SECRET="scim-secret"
SCIM_APPLICATION_ID="scim-application"
SCIM_SCOPE="scim"

If you are planning to use either the Remote Access or Secure Web Sessions endpoints you must set the following values in the .env file:

# Remote Access Login Information
RA_BASE_URL="api.alero.io"
RA_TENANT_ID="12ed12ae1EXAMPLEfb8d6e1234"
RA_SERVICE_ACCOUNT_ID="11ef91EXAMPLE415dc11bf4"
RA_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\r\nMIIEEXAMPLEowIBAAEXAMPLEu6p44EHG5f7QqREXAMPLEQ\r\n-----END RSA PRIVATE KEY-----\r\n"
RA_REGION="us"

# Secure Web Sessions Login Information
SWS_BASE_URL="api.alero.io"  
SWS_TENANT_ID="12ed12ae1EXAMPLEfb8d6e1234"
SWS_SERVICE_ACCOUNT_ID="11ef91EXAMPLE415dc11bf4"
SWS_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\r\nMIIEEXAMPLEowIBAAEXAMPLEu6p44EHG5f7QqREXAMPLEQ\r\n-----END RSA PRIVATE KEY-----\r\n"
SWS_REGION="us"

You can find your Tenant ID by logging into your SWS or Remote Access portal. The Tenant ID is located in the URL of the portal. Your base URL will depend on your region and can be found in the documentation. The Service Account ID can be found in the Service Account ID and Private Key are part of the JSON file that gets created when you create a service account.

(back to top)

Usage: API Troubleshooting and Testing

The various APIs have the ability to be used in automated testing and troubleshooting. The APIs can be run in Bruno and the responses can be viewed in the response tab or within the developer view depending on .env variables. The responses can be used to troubleshoot issues with the API or to test the API in an automated fashion.

There are two environment variables you may enable for test puporpses:

TEST_FLAG=true
TEST_LOG_VERBOSE=true

The first variable, TEST_FLAG, will enable the test mode for the API. This will allow you to run the API in a test mode. Note that when TEST_FLAG is set to true variables configured with in the UI may be overwritten by test variables sourced from the .env file. The following example shows how variables may be set as part of the Pre Request script when the TEST_FLAG is set to true:

const tools = require('./tools/tools');

// Sets pasSafeUrlId for testing based on environment flag and variables
var flag = bru.getEnvVar('testFlag')
if (flag == 'true') {
  tools.log('Setting Variables');
  bru.setVar('pasSafeUrlId', bru.getEnvVar('testSafeName'));
  tools.log('SafeName: ' + bru.getEnvVar('testSafeName'))
}

The following example shows how variables may be set as part of the Post Response when the TEST_FLAG is set to true:

const tools = require('./tools/tools');

// Sets Connector Id, Component Name, and version for testing based on environment flag and variables
var flag = bru.getEnvVar('testFlag')
if (flag == 'true') {
  tools.log('Setting Variables');
  bru.setVar('connector_id', res.body.components[0].connectorId);
  bru.setVar('component_name', res.body.components[0].componentName);
  bru.setVar('version', res.body.components[0].version);
  tools.log('Connector Id: ' + bru.getVar('connector_id'))
  tools.log('Component Name: ' + bru.getVar('component_name'))
  tools.log('Version: ' + bru.getVar('version'))
}

The second variable, TEST_LOG_VERBOSE, will enable verbose logging for the API. This will allow you to see the full errors within the developer console. This is useful for troubleshooting issues with the API. The example below logs errors anytime the response is not a 200 status code:

const tools = require('./tools/tools');

// Log on error
if (res.status != 200) {
  if (res.body.code) {
    tools.log('Code: ' + res.body.code);
  }
  if (res.body.message) {
    tools.log('Message: ' + res.body.message);
  }
  if (res.body.description) {
    tools.log('Description: ' + res.body.description);
  }
  if (res.body.details) {
    tools.log('Details: ' + res.body.details);
  }
}

(back to top)

Roadmap

• Add Self Hosted API Endpoints
• Add Remaining SaaS API Endpoints
  • Endpoint Privilege Manager
  • Identity
  • Secure Web Sessions
  • Remote Access
• Add Changelog
• Add more examples
• Add development documentation
• Ensure documentation is updated for endpoints
  • SaaS
    • Cloud Visibility
    • Conjur Cloud
    • Connector Managent
    • Identity
    • Endpoint Privilege Manager
    • Privilege Cloud
    • Secrets Hub
    • Secure Cloud Access
    • Secure Infrastructure Access
    • Secure Web Sessions
    • Remote Access
  • Self Hosted
    • PAM

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

Top contributors:

License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

Contact

Joe Strickland - @joestrick - joseph.a.strickland@gmail.com

Project Link: https://github.com/strick-j/CyberArk-APIs

(back to top)

Acknowledgments

• Joe Garcia
• Bruno
• Img Shields

(back to top)