API guide

Overview

BeyondTrust administrators can configure U-Series Appliances without going through the web-based interface. A PowerShell sample script has been used for demonstration, but BeyondTrust does not prescribe any implementation language or mechanism.

Configuration workflow

The flow for setup and configuration will be:

1. Call Set Window license or Skip license page endpoint (As image is not licensed)
2. Call Deployment web service
3. Wait for Deployment web service to finish by calling the Deployment Status endpoint
4. Call Configuration web service
5. Wait for Configuration web service to finish by calling the Configuration Status

ℹ️

Note

A valid BeyondInsight serial key must be passed through a HTTP header on each call.

U-Series Appliance web services

This portion of the guide details the U-Series Appliance web services (also referred to as endpoints). There are two endpoints in the U-Series Appliance: one to run the configuration, and one to monitor progress.

POST

/ApplianceGateway/api/BaseProductLicense/setwindowslicense

Endpoint to set Windows license.

POST

/ApplianceGateway/api/BaseProductLicense/skippage

Endpoint to skip Windows license page.

POST

/ApplianceGateway/api/DeploymentWizardAutomation

Endpoint to programmatically execute the deployment wizard.

GET

/ApplianceGateway/api/DeploymentWizardAutomation

Endpoint to get the status of the deployment wizard step execution. This is intended to be used after the Post in this controller has been called, to be able to poll the status as the steps are executed.

Sample response format

{    
    "stepsStatus": [
        {
            "name": "Initialize SQL Server",
            "outcomeInfo": {
                "stepStatus": 2,
                "stepOutcomeMessage": "SQL Server Initialization succeeded"
            }
        },
        {
            "name": "Rename appliance",
            "outcomeInfo": {
                "stepStatus": 2,
                "stepOutcomeMessage": "Appliance renamed to automation"
            }
        },
        {
            "name": "Apply time settings",
            "outcomeInfo": {
                "stepStatus": 2,
                "stepOutcomeMessage": "Applied time settings"
            }
        },
        {
            "name": "Reboot appliance",
            "outcomeInfo": {
                "stepStatus": 2,
                "stepOutcomeMessage": "Reboot requested"
            }
        },
        {
            "name": "Pause the wizard while waiting for a reboot",
            "outcomeInfo": {
                "stepStatus": 2,
                "stepOutcomeMessage": "Pausing for reboot"
            }
        },
        {
            "name": "Create BeyondInsight EMS certificate",
            "outcomeInfo": {
                "stepStatus": 2,
                "stepOutcomeMessage": "Created the BeyondInsight EMS certificate"
            }
        },
        {
            "name": "Apply IP settings",
            "outcomeInfo": {
                "stepStatus": 2,
                "stepOutcomeMessage": "IP settings applied"
            }
        },
        {
            "name": "Generate unique BeyondInsight cryptokey",
            "outcomeInfo": {
                "stepStatus": 2,
                "stepOutcomeMessage": "Generated unique BeyondInsight cryptokey"
            }
        }
    ],
    "overAllStatus": 2
}

POST

/ApplianceGateway/api/ConfigurationWizardAutomation

Endpoint to programmatically execute the configuration wizard.

GET

/ApplianceGateway/api/ConfigurationWizardAutomation

Endpoint to get the status of the configuration wizard step execution. This is intended to be used after the Post in this controller has been called, to be able to poll the status as the steps are executed.

Sample response format

{
    "stepsStatus": [
        {
            "name": "Apply License Settings",
            "outcomeInfo": {
                "stepStatus": 2,
                "stepOutcomeMessage": "License settings applied"
            }
        },
        {
            "name": "Prepare local BeyondInsight Database",
            "outcomeInfo": {
                "stepStatus": 2,
                "stepOutcomeMessage": "Local BeyondInsight database prepared for use"
            }
        },
        {
            "name": "Apply Backup Settings",
            "outcomeInfo": {
                "stepStatus": 2,
                "stepOutcomeMessage": "Backup settings applied"
            }
        },
        {
            "name": "Apply BeyondInsight Credentials",
            "outcomeInfo": {
                "stepStatus": 2,
                "stepOutcomeMessage": "BeyondInsight Credentials applied"
            }
        },
        {
            "name": "Apply Central Policy password",
            "outcomeInfo": {
                "stepStatus": 2,
                "stepOutcomeMessage": "Central Policy password applied"
            }
        },
        {
            "name": "Apply Updater Credentials",
            "outcomeInfo": {
                "stepStatus": 2,
                "stepOutcomeMessage": "Updater Credentials applied"
            }
        },
        {
            "name": "Apply Updater Settings",
            "outcomeInfo": {
                "stepStatus": 2,
                "stepOutcomeMessage": "Updater settings applied"
            }
        },
        {
            "name": "Apply PowerBroker for Windows",
            "outcomeInfo": {
                "stepStatus": 2,
                "stepOutcomeMessage": "PowerBroker for Windows applied"
            }
        },
        {
            "name": "Apply SSL Certificate Settings",
            "outcomeInfo": {
                "stepStatus": 2,
                "stepOutcomeMessage": "SSL certificate applied"
            }
        },
        {
            "name": "Apply Features",
            "outcomeInfo": {
                "stepStatus": 2,
                "stepOutcomeMessage": "Features applied"
            }
        },
        {
            "name": "Apply SMTP settings",
            "outcomeInfo": {
                "stepStatus": 2,
                "stepOutcomeMessage": "Applied SMTP settings"
            }
        },
        {
            "name": "Apply Internet Connection Settings",
            "outcomeInfo": {
                "stepStatus": 2,
                "stepOutcomeMessage": "Internet Connection Settings applied"
            }
        }
    ],
    "overAllStatus": 2
}

GET

/UVMInterface/api/UVMConfiguration/IsApplianceConfigured

Endpoint to get the status of the appliance configuration.

ℹ️

Note

Once complete, the configuration and deployment end points will be removed, and if the deployment or configuration is called, a 502 will be returned by the gateway.

GET

/ApplianceGateway/api/ApplianceInfoAutomation

Endpoint to get the network details.

Sample response format

{
    "ipSettings": [
        {
            "networkAdapter": " networkAdapter ",
            "networkCardId": "0",
            "useDhcp": true,
            "macAddress": null,
            "domainIp": "XX.XXX.XX.XXX",
            "subnetMask": "XXX.XXX.XXX.X",
            "defaultGateway": "XX.XXX.XX.X",
            "preferredDnsServer": "XX.XXX.X.XX",
            "alternateDnsServer": "XX.XXX.X.XX",
            "dnsSuffix": " dnsSuffix ",
            "modifiedSetting": false
        }
    ]
}

Prerequisite before deployment

Run Set Windows license or Skip License Page endpoint as Windows is not licensed.

Set windows license

Route

/ApplianceGateway/api/BaseProductLicense/setwindowslicense

Windows key JSON will be sent to the web service.

Sample JSON format

{
    "key": "XXXXX- XXXXX - XXXXX - XXXXX - XXXXX "
}

Skip windows license page

Route

/ApplianceGateway/api/BaseProductLicense/skippage

Empty JSON will be sent to the web service.

Deployment wizard

Route

/ApplianceGateway/api/DeploymentWizardAutomation

ℹ️

Note

A valid BeyondInsight license key must be passed through a HTTP header

The Deployment JSON will be sent to the web service and will include:

• Windows User credentials
• Licensing Agreements
• Appliance Name
• IP Settings
• Internet Connection Settings
• Time zone and Time Settings
• SMTP Settings

Sample JSON format

{
  "configureUser": {
    "username": "btadmin",
    "password": "password",
    "email": "[email protected]"
  },
  "licenseAgreement": {
    "acceptBtEula": true,
    "acceptMsEula": true,
    "acceptSqlServerEula": true
  },
  "applianceName": {
    "applianceName": "applianceName"
  },
  "ipSettings": [
    {
      "networkAdapter": "networkAdapter",
      "networkCardId": "",
      "useDhcp": true,
      "macAddress": "",
      "domainIp": "XX.XXX.XX.XXX",
      "subnetMask": "XXX.XXX.XXX.X",
      "defaultGateway": "XX.XXX.XX.X",
      "preferredDnsServer": "XX.XXX.X.XX",
      "alternateDnsServer": "XX.XXX.X.XX",
      "dnsSuffix": "dnsSuffix",
      "modifiedSetting": false
    }
  ],
  "internetConnectionSettings": {
    "connectThroughProxy": true,
    "proxySetting": {
      "proxyAddress": "XX.XXX.XX.XXX",
      "proxyPort": 808,
      "proxyUsername": "",
      "proxyPassword": ""
    }
  },
  "timeSettings": {
    "syncType": 0,
    "ntpServer": "ntpServer",
    "timezone": "Central Standard Time"
  },
  "smtpSettingsDto": {
    "emailServer": "emailServer",
    "smtpPort": 25,
    "ssl": true,
    "requiresAuthentication": false,
    "username": "username",
    "password": "password"
  }
}

Configuration wizard

Route

/ApplianceGateway/api/ConfigurationWizardAutomation

ℹ️

Note

A valid BeyondInsight license key must be passed through a HTTP header.

The Configuration JSON will be sent to the web service and will include:

• BeyondTrust Licenses
• Solution & Roles
• User Credentials
• Roles Configuration
• Backup And Restore
• Update Method

Sample JSON format

{
  "license": {
    "licenseMode": 0,
    "serialNumber": "",
    "licenseKey": ""
  },
  "rolesSelected": {
    "sqlServerRole": true,
    "analysisServerRole": true,
    "sqlServerReportingServicesRole": true,
    "beyondInsightDatabaseAccess": true,
    "beyondInsightManagementConsole": true,
    "omniworkerRole": true,
    "eventCollectorRole": true,
    "passwordSafeConsoleRole": true,
    "biulSetupRole": false,
    "discoveryScannerRole": true,
    "epmDatabaseRole": true,
    "epmEventCollectorRole": true,
    "epmPrivilegeManagementReportingRole": true,
    "epmWebPolicyEditorRole": true
  },
  "credentials": {
    "biUserName": "btadmin",
    "biUserPassword": "password",
    "cpPassword": "password",
    "btUpdaterName": "btadmin",
    "btUpdaterPassword": "password",
    "biulUsername": "btadmin",
    "biulPassword": "password"
  },
  "roleConfigurationBiul": {
    "biulIsRemote": true,
    "biulServerName": "XX.XXX.XXX.XX",
    "biulSqlUser": "username",
    "biulSqlPassword": "password",
    "biulDatabaseName": "PBSMC",
    "biulPort": 0,
    "biulDbInstance": "InstanceName"
  },
  "roleConfigurationRemoteSql": {
    "biIncomingDatabasePassword": "password",
    "allowIncomingDatabaseConnections": false
  },
  "roleConfigurationSqlAccess": {
    "biConnectionServerName": "ServerName",
    "biConnectionDatabaseName": "RetinaCsDatabase",
    "biCommandTimeout": 300,
    "biConnectionTimeout": 60,
    "biDatabaseConnectionStringUsername": "beyondtrust_user",
    "biDatabaseConnectionStringUserPassword": "password",
    "biDatabaseConnectionStringMultiSubnetFailover": false,
    "biCreateRemoteDatabase": false,
    "biDatabaseIsLocal": true,
    "biAdministratorUsername": "btadmin",
    "biAdministratorPassword": "password"
  },
  "roleConfigurationEpmDatabase": {
    "EpmConfigurationType": 1,
    "EpmServerName": "localhost",
    "EpmEcSqlUser": "epmEventCollector",
    "EpmEcSqlPassword": "password",
    "EpmRrSqlUser": "epmReportReader",   
    "EpmRrSqlPassword": "password"
  },
  "backupRestore": {
    "backupOption": 1,
    "backupSetting": {
      "path": "path",
      "username": "",
      "password": "",
      "domain": "",
      "startTime": "2021-07-19T18:55:51.522Z",
      "frequency": 0,
      "backupPassword": "password"
    }
  },
  "updates": {
    "updatesOption": 0,
    "serverAddress": "ServerAddress"
  }
}

PowerShell script descriptions

ℹ️

Note

Set Windows license endpoint or skip license page endpoint must be called before running scripts.

There are a total of four sample files, as follows:

• DeploymentUSeries.ps1: PowerShell script to be called for deployment of appliance
• Deployment.json: Contains sample JSON format used by the deployment script (DeploymentUSeries.ps1)
• ConfigurationUSeries.ps1: PowerShell script to be called for configuration of appliance
• Configuration.json: Contains sample JSON format used by the configuration script (ConfigurationUSeries.ps1)

DeploymentUSeries.ps1

This file contains the PowerShell script that calls the deployment endpoint. This must be the first script called. You must pass three parameters in this script, as follows:

• $UvmAddress: IP of U-Series Appliance

✅

Example

Replace “XX.XXX.XXX.XXX” with an actual IP of U-Series Appliance in DeploymentUSeries.ps1 script.

• $InputFileName: Name of the file which contains JSON Data to be passed to the deployment endpoint. In this case, the value is DeploymentUSeries.ps1. If you are using your own file, then this is name of that file. You can edit this value in the DeploymentUSeries.ps1 file according to the requirement.
• $Header: You must pass header with key “SerialNumber” and value “actual serialnumber”.

✅

Example

Replace “XXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX” with an actual serial number in DeploymentUSeries.ps1 script.

Deployment.json

This file contains sample JSON format used by the deployment script. You can edit the values according to the requirement.

Deployment script results

After running the deployment script, one of the following outputs displays:

• Deployment Completed: Implies that deployment is successful.
• Deployment Failed: Implies that deployment is failed and displays an error message. You can work on the error and rerun the script.

ℹ️

Note

This script returns a Not halting script message when the endpoint will not be available during restart.

ConfigurationUSeries.ps1

This file contains the PowerShell script that calls the configuration endpoints. This must be the second script to be called after deployment script. You must pass three parameters in this script, as follows:

• $UvmAddress: IP of U-Series Appliance.

✅

Example

Replace “XX.XXX.XXX.XXX” with actual IP of U-Series Appliance in ConfigurationUSeries.ps1 script.

• $InputFileName: Name of the file which contains JSON Data to be passed to the configuration endpoint. In this case, the value is Configuration.psd1. If you are using your own file, then this is the name of that file. You can edit this value in the ConfigurationUSeries.ps1 file according to the requirement.
• $Header: Need to pass header with key “SerialNumber” and value “actual serial number”.

Configuration.json

This file contains sample JSON format used by the configuration script. You can edit the values according to the requirement.

Configuration script results

After running the configuration script, one of the following outputs displays:

• Configuration Completed: Implies the configuration is successful.
• Configuration Failed: Implies the configuration failed and displays an error message. You can then work on the error and rerun the script.

Troubleshoot failures in the U-Series Appliance API

Failure scenarios

• If a 401 error is received from the API, it means either the alpha feature has not been enabled or the U-Series Appliance has already been configured.

• If an error is encountered during the configuration, a status message is returned when checking the API, that states that an error occurred and indicates at which step it initially failed.

  The next step is for the user is to attempt to resolve this manually and run the Configuration Wizard again through the current https:///ConfigurationWizard. Alternatively, the user can redeploy the image and try again. The configuration API cannot be run a second time.

BeyondTrust U-Series Appliance Parameters

U-Series Appliance parameters

Omit parameters

In the U-Series Appliance, not all parameters need to be passed for every scenario. You can omit those parameters that are not needed. This scenario is demonstrated in the sample data for the example scripts.

Select 1 for proxy

✅

Example

If you select 1 for proxy, these parameters are not needed:

• ProxyAddress
• ProxyPort
• ProxyUsername
• ProxyPassword

Local SQL

✅

Example

If Local SQL is installed, these parameters are not needed:

• RemoteDbCommandTimeout
• RemoteDbDatabaseName
• RemoteDbMultiSubnetEnabled
• RemoteDbPassword
• RemoteDbServerName
• RemoteDbConnectionTimeout
• RemoteDbUserName

Cloud platforms

✅

Example

For cloud platforms these parameters are needed: PasswordRemAdminCurrent

In any other scenario, this parameter is not required.

Parameters

Timezone parameters

The TimeZoneName parameter can be one of these strings: