MIDDLEWARE ENGINE GUIDE

The BeyondTrust Middleware Engine is a Windows service that is the backbone for integrations with BeyondTrust Remote Support. The BeyondTrust Middleware Engine provides a plugin integration architecture: a plugin can be developed and deployed to the product, and the product provides data and administrative services to the plugin.

This document provides general information on plugin deployment using the BeyondTrust Middleware Engine. Deployment of a specific plugin is beyond the scope of this document. For that information, refer to documentation for the specific plugin.

Start BeyondTrust Middleware Engine

The BeyondTrust Middleware Engine runs as a Windows service. This service must be restarted whenever a new plugin is deployed or a plugin is removed.

Launch the middleware administration tool

Once the Windows service is running, the middleware administration tool can be launched. Open a web browser on the server and go to http://127.0.0.1:53231/. This tool is accessible only from the server where the BeyondTrust Middleware Engine is installed. If necessary, the tool can run on a different port, and it can be turned on/off as desired.

ℹ️

Note

For more information, see Configure the middleware administration tool.

Overview of the middleware administration tool

The home page of the middleware administration tool displays all deployed plugins as well as each plugin's configuration(s). Multiple plugin configurations can be created. Creating multiple plugin configurations allows a single plugin to integrate with multiple systems, such as two different B Series Appliances.

Add and edit plugin configurations

To add a new configuration for a deployed plugin, click the copy icon next to the plugin name. A window displays the copied configuration details, including connection information to a B Series Appliance and any plugin-specific settings.

This screen also includes an option to disable a plugin configuration.

For a specific plugin configuration, the following options are available:

• Edit the plugin configuration.

• Test the plugin configuration. Testing confirms that the plugin is configured correctly and that network resources can be accessed.

• Delete the plugin configuration. The configuration cannot be recovered after deletion.

ℹ️

Note

Configuration changes made via the middleware administration tool are immediately effective. It is not necessary to restart the Windows service.

View plugin event history

To view the event history for a plugin, click the history icon next to the plugin name. A page shows key details of each event the plugin has processed. The period history available depends on the event retention configured in the middleware administration tool. The default is seven days.

On the plugin events page, the following functionality is available:

• Page and filter text
• View raw event data
• View error data if event processing failed.
• Find the event GUID, an identifier attached to every log message for the event.
• Replay an event (i.e., sending the event to the plugin to reprocess). This can be useful for events that fail for transient reasons, such as a network issue.

ℹ️

Note

For information on how to change this event retention setting, see Configure the middleware administration tool.

Work with the event retries for a plugin

To view the active retries for a plugin, click the clipboard icon located next to the history icon. A page displays details about each retry.

The retry is removed from this page when the plugin:

• Successfully processes the event
• Reaches the retry limit

The retries are attempted using a Fibonacci backoff strategy. This strategy staggers the retries, with the first attempt taking place five seconds after the initial failure. The maximum number of retries is set in the plugin configuration. The Retry Events page provides the functionality required to replay the event before the next attempt time.

Configure the middleware administration tool

You can modify the middleware administration tool to run on a different port, and you can turn it on or off as desired. You also can change the length of time that events are stored.

From the home page of the middleware administration tool, click the Edit Middleware Configuration link.

1. The following configuration options are available:
   • Logging Level: Defines the logging level for the BeyondTrust Middleware Engine. Modifications to this value take effect immediately. For maximum logging, select DEBUG. For minimum logging, select ERROR.
   • Outbound Event Base Address: The base address BeyondTrust Middleware Engine listens to for outbound events from a B Series Appliance. If this value is changed, the Windows service must be restarted.
   • Middleware Administration Tool Enabled: If disabled, the web-based tool is not available. If this value is changed, the Windows service must be restarted.
   • Middleware Administration Tool Base Address: The base address on which the administration tool runs. If this value is changed, the Windows service must be restarted.
   • Event Retention Days: The number of days to keep a record of events delivered to plugins. If this value is changed, the Windows service must be restarted.
2. If desired, this configuration can be edited from a file, for example, when the administration tool is disabled.
   • Go to the directory where the BeyondTrust Middleware Engine is installed.
   • In a text editor, open MiddlewareConfig.txt.
   • Edit the file as needed. The file is in JSON format. Valid LogLevel values are ERROR, INFO, WARN, and DEBUG.

ℹ️

Note

When changing the LogLevel from the text file, the change is not immediately effective. The log level can change dynamically only when it is changed from the administration tool user interface.

• Below is the default configuration:

{
    "LogLevel": "ERROR",
    "EngineBaseAddress": "http://+:8180/",
    "AdminToolEnabled": true,
    "AdminToolBaseAddress": "http://127.0.0.1:53231/",
    "EventRetentionDays": 7
                }

• After making any changes, restart the Windows service.

Install middleware engine

Review prerequisites

Before installing the software, ensure your system meets the following hardware, software, and network requirements.

Confirm Remote Support versions

• A currently supported version of BeyondTrust Remote Support. To confirm your version is supported, Contact Support or refer to the BeyondTrust End of Life Policy.
• BeyondTrust Middleware Engine: 1.0.0.0 or later.

Open network ports

The following network communication channels must be open for the BeyondTrust Middleware Engine to work properly.

Confirm server requirements

The BeyondTrust Middleware Engine requires installation on Windows Server 2016 or higher. See specific requirements below.

Review other requirements

Visual C++

Visual C++ Redistributable Package for Visual Studio 2015 or later is required by the BeyondTrust Middleware Engine. If not already present when the BeyondTrust Middleware Engine setup file is run, this package is installed automatically.

.NET 4.6.2

.NET 4.6.2 or later is required by BeyondTrust Middleware Engine. If not already present when the BeyondTrust Middleware Engine setup file is runNET 4.6.2 is installed automatically.

BeyondTrust Middleware Engine installation

Run bomgar-middleware-engine.exe, following on-screen instructions. If either Visual C++ Redistributable Package for Visual Studio 2015 or .NET 4.6.2 are not already installed on the server, they are installed at this time.

Verify installation

Follow the steps below to verify the installation.

1. Open the services management console by typing services.msc in the Windows Run dialog.

2. Locate the service BeyondTrust Middleware Engine.

3. Start the service.

4. Open a web browser on the server and go to http://127.0.0.1:53231/.

   The home screen of the BeyondTrust middleware administration tool opens. A No plugins were found! message is normal at this point, because no plugins have yet been deployed.

ℹ️

Note

This tool is accessible only from the server where the BeyondTrust Middleware Engine is installed. If necessary, the tool can run on a different port, and it can be turned on and off as desired. For details, see Configure the Middleware Administration Tool.

Deploy a new plugin

Plugins are typically provided in a ZIP file. To install and enable a new plugin from the ZIP file:

1. Save the ZIP file to a folder on the host machine.
2. Extract the ZIP file to the same folder.
3. In the extracted contents, locate the folder with the plugin’s name (for example, BeyondTrustERSOtherVendorPlugin).
4. Copy that folder and paste it into the Plugins folder, located in the directory where the BeyondTrust Middleware Engine is installed.
5. To enable the new plugin, the Middleware Engine service must be restarted. Repeat the steps above in Verify installation to restart the service.
6. The new plugin displays on the administration tool landing page.

Manually locate deployed plugins

Each plugin is deployed into its subfolder of the Plugins folder. The Plugins folder is in the directory where the BeyondTrust Middleware Engine is installed.

Once a plugin has been configured in the Middleware Engine, a file named .config is present. The plugin's folder might contain any number of other files and folders, depending on the plugin.

Set up reverse proxy

Use IIS as a reverse proxy for the BeyondTrust Middleware Engine

The following steps show you how to set up and configure IIS to work as a reverse proxy for the BeyondTrust Middleware Engine. This supports scenarios where outbound events from the B Series Appliance must go over port 443, such as outbound events from BeyondTrust Cloud.

ℹ️

Note

These instructions require that the outbound event setup for installing the middleware engine has been completed.

1. In the IIS Server Manager dashboard, click Add roles and features.
2. Click Next on the next screen.
3. Under Select installation type, select Role-based or feature-based installation. Click Next.
4. Under Server Selection, choose Select a server from the server pool and select the desired server. Click Next.
5. Under Server Roles, select Web Server (IIS). Click Next.
6. When you select Web Server (IIS), you are prompted to add IIS management tools. Click Add Features.
7. Make sure that .NET Framework 4.6 Features is checked, and then click Next. You do not need to select any additional features.Under Web Server Role (IIS), click Role Services on the left menu. Check that the necessary default values are checked.
8. Click Next, then Install.
9. A progress bar indicates that the installation is taking place. When the installation is complete, click Close.

Install additional IIS modules

If not already installed:

• Download and install the Microsoft IIS URL Rewrite module.
• Download and install the Microsoft IIS Application Request Routing module.
• Restart the World Wide Web Publishing Service.

Set up SSL

1. Open the IIS Manager application, and then click the server name on the left pane.
2. Click Server Certificates.
3. In the Actions menu, choose to Import your certificate. If a CA certificate is not available, or the configuration is for a development or testing site, you can select Create a Self-Signed Certificate.
4. On the right panel, under Sites, select the Default Web Site.
5. From the Actions menu, click Bindings.
6. Add a binding and choose type https.
7. Choose the SSL certificate you imported or created in the previous step.

Configure the reverse proxy

1. On the right panel, under Sites, select Default Web Site.
2. Double-click URL Rewrite.
3. Click Add Rule(s)...
4. Select Reverse Proxy. If prompted to enable proxy functionality, click OK.
5. Enter 127.0.0.1:8180 as the server name and leave other options as default.
6. Restart the Default Web Site.

Set up optional BeyondTrust outbound event to validate the certificate

If desired, you may set up the B Series Appliance to validate the server certificate when sending an outbound event.

ℹ️

Note

You must have a valid CA certificate in IIS for this setting to work.

1. In the B Series Appliance, navigate to Management > Outbound Events.
2. Edit the desired outbound event.
3. Enable the CA Certificate option. Click Choose File and select your CA certificate.

Troubleshooting