Configuring the Generic REST API on-premises connector

As an automation engineer, you configure the connector and the actions supported by the connector are displayed while creating a policy.

To configure a connector, the high-level process includes the following steps:

Related topics

Managing automation policies

Managing connectors

Deprecated and discontinued features

Authentication mechanisms for the Generic REST API connector

The Generic REST API connector allows connecting with any application that supports RESTful APIs. While configuring the connector, you must use one of the following supported authentication methods:

Authentication mechanism	Fields required	Description
Basic	Username Password	Use the username and password required to log on to the REST APIs of the endpoint application.
Bearer	API key Token REST API login URL Parameters required to log on to the endpoint application, for example, username and password	For example, if you want to connect to Jira REST APIs, while configuring the credentials in Task #3, you can specify the API key, the REST API login URL for Jira, and the username and password for the login URL. BMC Helix Intelligent Automation logs in to Jira, retrieves the token information from the field specified in the API key, and connects to the application.
API key	API key Supported fields: request header query string cookie Name of the header, query parameter, or cookie	For example, if you are connecting to the Rundeck Ansible Tower APIs by using API key-based authentication, you need to specify Header and use the X-Rundeck-Auth-Token field as the header name while configuring the connector. The field name from which BMC Helix Intelligent Automation retrieves the token is specified in the API key.
Cookie-based authentication	API key Cookie Name of the cookie field	For example, if you want to connect to BMC Helix ITSM by using the REST API connector, you can specify these parameters while configuring the credentials in Task #3.

Before you begin

Before you configure the on-premises connector, ensure that you the following conditions are met:

The server where you want to run and install the remote plugin matches the minimum requirements.
For more information, see System requirements.
(For Linux) The GCC G++ compiler version is 5.4.0 or later.
Click here to do the steps before you run the plugin
1. Install and update GCC version 5.4.0 or later.
2. Run the following command to unlink the current version.
```
sudo unlink /usr/lib64/libstdc++.so.6
```
3. Run the following command to copy the new version.
```
sudo cp /usr/local/lib64/libstdc++.so.6 /usr/lib64
```

Task 1: To create a plugin key

Click Connectors > Plugin Keys tab.
Click Create Plugin Key and do the following steps:
1. (Optional) Enter a new name for the plugin with which you want to associate the plugin key.
2. (Optional) Update the expiry date for the plugin key.
  By default, a plugin key expires in 90 days. To ensure that the connector is running, you can extend the date before it expires.
3. Click Download Plugin Key.
  A creds.json file gets downloaded.
  Warning
  
  If you close the Create Plugin Key panel before downloading the key, you cannot download and use the plugin key. Instead, you need to create a new plugin key.
Click Save.
The plugin and the associated plugin key appear on the Plugins page.

Optional Task: To reuse an existing plugin key

If you have configured any on-premises connector, you already have a plugin key. You can use the same key to configure any other on-premises connector.

Click Connectors > Available Connectors and click Configure against the connector that you want to configure.
On the following message that appears on the configure connector page, click the download & install link.

On the Configure On-premises Connector page, the plugin keys available for reuse are displayed.
Skip Task 2 and continue with Task 3 to configure the connector.

Task 2: To download the plugin

You can download and run a plugin on a Linux or a Microsoft Windows server. This server should be accessible from the computer where the automation tool or application is installed.

In the BMC Helix Intelligent Automation console, click Connectors > Available Connectors and click Configure against the connector.
On the following message that appears on the configure connector page, click the download & install link.
On the Configure On-premises Connector page, click Download Plugin.
The remote-restapi-plugin.zip file is downloaded.
Copy and extract the downloaded ZIP file and go to the remote-restapi-plugin directory.
Go to the remote-restapi-plugin\config location and and replace the creds.json file with the credential file generated in Task 1.
(For Linux only) Ensure that the run.sh file has the execute permission.

Optional task: To use a pass-through proxy server

If the host where you download the plugin to configure a connector does not have internet access, you can use a proxy server to configure the connector. The host where the connector is to be configured and the automation tool must be in the same network domain. You can also configure the proxy server with basic authentication mechanism.

Navigate to the remote-restapi-plugin directory.

Run the following command to create credentials for the proxy server without any authentication.

For Linux

 credential.sh create -n proxy -i <hostname:port of the proxy server> -p proxy -a noauth

For Windows

credential.bat create -n proxy -i <hostname:port of the proxy server> -p proxy -a noauth

Run the following command to create credentials for the proxy server with basic authentication.
```
credential.bat create -n proxy -i <hostname:port of the proxy server> -p proxy -a basic
```
When prompted, enter the username and password for the proxy server.
Continue to the next task.

Task 3: To create credentials by using the plugin key

A plugin requires credentials to authenticate and execute various actions on the target applications that are defined in an automation policy. The credential CLI utility enables you to create, search, update, and delete credentials for a plugin. This server should be accessible from the server where the on-premise application is installed.

Navigate to the directory where you have extracted the remote-restapi-plugin.zip file.
The remote-restapi-plugin directory contains credential.sh.
Ensure that the credential.sh file has the execute permission.
Run the following create switch command to create credentials.
Whenever credentials are created, a unique credential ID is assigned to it.
Sample command for Microsoft Windows
```
credential.bat create -n <credentialsName> -i <http://host:port> -p <provider> -a <AuthenticationType>
```
Sample command for Linux
```
./credential.sh create -n <credentialsName> -i <http://host:port> -p <provider> -a <AuthenticationType>
```
Sample command for using API key authentication
```
./credential.sh create -n <credentialsName> -i <endpoint_url> -p generic_rest -a apikey <apikeyvalue>
```
Example command
```
credential.bat create -n jira_connector -i https://jira.atlassian.net -p generic_rest -a basic
```
Here,
- jira_connector is the name of the connector
- https://jira.atlassian.net is the location where the endpoint application is available
- generic_rest is the provider ID
- basic is the authentication type
  Note
  
  If the endpoint application supports API key authentication, you can specify a static API key to configure the connector.
Enter the username and password when prompted.

(Optional) If using the API Key authentication method, enter the values for the following parameters as prompted:

Parameter Value

api key

Enter the static API key generated from the endpoint application.

Example: apiKey <apikeyvalue>

In the example, apikey is used as a prefix. Depending on the endpoint application that you are trying to connect to by using the API key, specify the accurate prefix.

login required Enter n.

After you provide the credentials based on the authentication type, credentials are created successfully.

Task 4: To provide a server-side SSL certificate

To configure the plugin to connect to any of the products running on HTTPS/SSL, do the following steps:

Download the server-side certificate and convert it into a .PEM format.
In case of multiple products, convert and merge all individual certificates into a single .PEM file.
Copy and place the certificate in the server-certs directory located in the remote-restapi-plugin directory.
Continue to the next step to start and run the plugin.

Optional task: To start or run the plugin by using HTTPS

When you start or run the plugin, by default, the plugin runs by using the HTTP protocol. To run it on the HTTPS protocol, you must generate the client-side certificates and update the properties in the plugin.properties file to enable the support. On Linux-based operating systems, client-side certificates are automatically generated and added to a client-certs folder.

If you want to run it on the HTTPS protocol, perform the following steps:

For Microsoft Windows only

Navigate to the remote-restapi-plugin directory.
Create a new folder with and name it client-certs.
Generate a client certificate and the key of the host, in a PEM format, where the plugin will run.
Copy the certificate to the client-certs folder.

For Microsoft Windows and Linux-based operating systems

Navigate to the remote-restapi-plugin\config and open the plugin.properties file.
The file contains the following new properties:

Sample

config.sslEnabled=false
config.sslPort=8443
config.sslCertPath=<pathToTheClientCertificate.pem file>
config.sslCertKeyPath=<pathToTheClientKey.pem file>

Specify the path to the folder where the certificate and key files are located.

Specify config.sslEnabled as true.

Example

config.sslEnabled=true
config.sslPort=8443
config.sslCertPath=client-certs/client_cert.pem
config.sslCertKeyPath=client-certs/client_key.pem

Save changes and continue to the next step.
When you start the plugin, it runs by using an HTTPS server.

Task 5: To start and run the plugin as a service

If a remote plugin is installed as a service, you can start, stop, or restart it as any other service. BMC recommends that you run the plugin as a service as against running it as a batch or shell process. You can run remote plugin as a service only on Microsoft Windows Server 2016 Enterprise and CentOS 7 operating systems.

Before running a plugin as a service, ensure that the following prerequisites are fulfilled:

You have administrative or root privileges on the host where the plugin is extracted.
The host where the plugin is available is also accessible from the host where the application is installed.

To run plugin as a service:

Navigate to the directory where you have extracted the remote-restapi-plugin.zip file.
Run the install.bat (for Microsoft Windows) or install.sh (for Linux) command.
You can also use the install.bat install command. The plugin now runs as a service.

If a service is installed successfully, in the list of services available in the Microsoft Windows Service Manager, the remote restapi plugin service is displayed. On Linux servers, if you run the install.sh status command, a system process with the name BMC remote-restapi-plugin appears.

Note

The credentials database is now stored at a new location. To ensure backward compatibility, copy the credential.db file from your previous location and place it in the new database location.

OS	Old location	New location
Microsoft Windows	`C:\Users\Public\bmc\ia_remote_plugins\database`	`C:/ProgramData/BMC/ia_remote_plugins/database/`
Linux	`/root/.bmc/ia_remote_plugins/database/`	`/var/lib/bmc/ia_remote_plugins/database/`

Optional: To start the plugin as a batch or shell process

After successfully creating the credentials, run the plugin to enable the connector.

Navigate to the remote-restapi-plugin/config directory, and replace the creds.json file with the creds.json file that you have downloaded while creating the plugin key.
Run the run.sh script to start the plugin.

Task 6: To test the plugin

BMC recommends that you test whether the plugin is able to connect to the automation tool or application successfully before creating automation policies.

In the BMC Helix Intelligent Automation console, click Connectors > PluginKeys.
Click Actions > Test against the plugin that is used to configure the connector.
A message appears that shows that the connection is successful.

The Generic REST API connector is configured and appears in the Configured Connectors tab.

Where to go from here

Now that the connector is configured successfully, you can create policies to execute actions in the target applications. For an example of adding actions to a policy, see Running a Jenkins job.