Configuring the Generic REST API on-premises connector

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:

Before you begin

Before configuring the on-premises connector, make sure that the following prerequisites are met: 

• The server where you want to run and install the remote plug-in matches the minimum hardware and software requirements.
  For more information, see System-requirements.
• The host where the remote plug-in utility is running is accessible from the host where the endpoint automation tool is installed. 
• You have the permissions required to install and configure an on-premises connector.
  For more information, see Roles-and-permissions. 

• (For Linux) The GNU Compiler Collection (GCC) G++ 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 latest version.

     sudo cp /usr/local/lib64/libstdc++.so.6 /usr/lib64

Task 1: To create a plug-in key

1. Log in to BMC Helix Intelligent Automation console, and click Connectors > Plugin Keys.
2. Click Create Plugin Key.
   The plug-in key details, the expiry date, and the default name are displayed. 
3. (Optional) Type the plug-in name.
4. (Optional) Click the calendar icon to update the expiry date.
   By default, the plug-in key expires in 90 days. 

5. Click Download Plugin Key.
   The creds.json file is downloaded. 

   Warning

   Download the plug-in key before closing the panel. If the panel is closed, the key cannot be downloaded again, and you will need to create a new one. 

   

6. Click Save.
   The plug-in key is displayed on the Plugins page with the status as Active. 

   Important

   You can use one plug-in key for multiple on-premises connectors. For more information about working with plug-in keys, see Editing-disabling-and-deleting-plugin-keys.

7. Continue with Task 2: To download the remote plug-in utility.

Optional Task: To reuse an existing plug-in key

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

1. Click Connectors > Available Connectors and click Configure against the connector that you want to configure.
   On the configure connector page, the plug-in keys available for reuse are displayed.
   
2. Skip Task 2 and continue with Task 3 to configure the connector.

Task 2: To download the remote plug-in utility

1. Click Connectors > Available Connectors and click Configure against the connector.
2. On the Configure On-premises Connector page, click Download Plugin.
   The remote-restapi-plugin.zip utility is downloaded.
3. Extract the downloaded ZIP file and navigate to the remote-restapi-plugin directory.
4. Navigate to the remote-restapi-plugin\config location and replace the creds.json file with the credential file generated in Task 1.

5. (For Linux only) Run the following command to provide the execute permission:

   chmod +x install.sh
6. Continue with Task 3: To create credentials for the connector. 

(Optional) Task 3: To use a pass-through proxy server

If the host where you want to install and run the plug-in does not have internet access, 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. 

1. Navigate to the remote-restapi-plugin directory.

2. 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 

3. 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, type the user name and password for the proxy server.

4. Continue to the next task. 
   If configuring the proxy server after a connector is installed and running, ensure that you start the connector service again. 

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 helps you to create, search, get, and delete credentials for a plugin. This server should be accessible from the server where the on-premise application is installed.

1. Navigate to the directory where you have extracted the remote-restapi-plugin.zip file.
   The remote-restapi-plugin directory contains credential.sh.
2. Ensure that the credential.sh file has the execute permission.

3. Run the following create switch command to create credentials.
   Whenever credentials are created, a unique credential ID is assigned to it.

   Commands to create credentials

   Microsoft Windows: credential.bat create -n <credentialsName> -i <http://host:port> -p <provider> -a <AuthenticationType>
   Linux: ./credential.sh create -n <credentialsName> -i <http://host:port> -p <provider> -a <AuthenticationType>

   Authentication type	Parameters
   - a apiKey	API key: When prompted, enter the API key  login required: n authentication parameter: apikey location: Select  the appropriate option: header, query, cookie
   - a bearer	JWT token: When prompted, enter the JWT token login required: n authentication parameter: apikey location: header
   - a basic	Username Password

   Example command for using API key authentication

   ./credential.sh create -n <credentialsName> -i <endpoint_url> -p generic_rest -a apikey 

   Example command for bearer authentication and proxy server

   ./credential.sh create -n <credentialsName> -i <endpoint_url> -p generic_rest -a bearer --use_proxy
   

   Sample command for basic authentication and proxy server

   ./credential.sh create -n jira_connector -i https://jira.atlassian.net -p generic_rest -a basic --use_proxy
   

   Here,

   • jira_connectoris the name of the connector
   • https://jira.atlassian.net is the location where the endpoint application is available
   • generic_rest is the provider ID

   •  basicis the authentication type

   • (Optional) use_proxy  specify whether a proxy server should be used to communicate between connectors and the endpoint automation tool. This parameter is valid if you have already configured a proxy server.

​​​​​​​ 

1. Enter the username and password when prompted. 
   After you provide the credentials based on the authentication type, credentials are created successfully.

2. (Optional) To create credentials in a single step, create a JSON file, which contains all the credentials required for configuring the connector, and run the following command:

   credential.bat create -n <ConnectorName> -i <hostname> -p generic_rest -a bearer -f C:\\Users\\Administrator\\Downloads\\auth_json_file.json

   Click here to view the sample JSON file

   {
       "auth": {
           "access_token": “<PARAMETER_To_GET_Token>”,
           "bearer_parameter": "Bearer",
           "login_action": {
               “<LOGIN_URL>”: {
                   "post": {
                       "parameters": [{
                               "headers": {}
                           },
                           {
                               "query": {}
                           }
                       ],
                       "body": {
                           "content": {
                               “<CONTENT-TYPE>”: {
                                   “<USERNAME>”:”<USERNAME_VALUE>”,
                                               “<PASSWORD>”:”<PASSWORD_VALUE>”
                                               ....
                                               ....
                               }
                           }
                       }
                   }
               }
           }
       }
   }

Task 5: To provide a server-side SSL certificate

BMC Helix Intelligent Automation requires certificates to establish a secure connection with the endpoint automation tool. If your automation tool runs on CA-signed certificates, skip this step. However, if you are using self-signed certificates, you must perform these steps for a secure and trusted connection. 

To configure the plug-in to connect to any of the automation tools running on HTTPS/SSL, do the following steps:

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

Optional task: To start or run the plug-in by using HTTPS

When you start or run the plug-in, by default, the plug-in 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

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

For Microsoft Windows and Linux-based operating systems

1. 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>
2. Specify the path to the folder where the certificate and key files are located.

3. 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
4. Save changes and continue to the next step. 
   When you start the plug-in, it runs by using an HTTPS server. 

Task 5: To start and run the plug-in as a service

If a remote plug-in is installed as a service, you can start, stop, or restart it as any other service. We recommend that you run the plug-in as a service instead of running it as a batch or shell process. 

Before running a plug-in as a service, make sure that the following prerequisites are fulfilled:

• The host where the plug-in is available is also accessible from the host where the application is installed.

• (For Linux) Run the following command to provide the execute permission:

  chmod +x install.sh

To run the plug-in as a service:

1. Navigate to the directory where you have extracted the remote-restapi-plugin.zip file.

2. Run the install.bat (for Microsoft Windows) or install.sh (for Linux) command.
   The following table lists the commands used to perform service-related actions:

   Command	Microsoft Windows	Linux
   Install	install.bat install	./install.sh install
   Start	install.bat start	./install.sh start
   Stop	install.bat stop	./install.sh stop
   Status	install.bat status	./install.sh status
   Uninstall	install.bat uninstall	./install.sh uninstall

3. When prompted, type the location for the credentials database. 
   If skipped, the database is stored at the default location. 

   Note

   The credentials database is 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/	{USER_HOME}/bmc/ia_remote_plugins/database

4. Run the following command to start the service:
   • Microsoft Windows: install.bat start
   • Linux: ./install.sh start
     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.

Optional: To start the plug-in as a batch or shell process

After successfully creating the credentials, run the plug-in to enable the connector. 

1. 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.
2. Run the run.sh script to start the plugin.

Task 6: To test the plug-in

We recommend that you test whether the plug-in is able to connect to the automation tool successfully before creating automation policies. 

1. In the BMC Helix Intelligent Automation console, click Connectors > PluginKeys.
2. Click Actions > Test against the plug-in that is used to configure the connector.
   The 

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

Where to go from here

• To configure the connector for high availability, see Configuring-high-availability-for-on-premises-connectors.
• To create automation policies by using the connector, see Running-a-Jenkins-job.