Connecting to a private network from the App Connect Dashboard (in IBM App Connect Operator 11.1.0 or later)

To use the App Connect Dashboard to deploy Designer or Toolkit integrations that interact with applications that run on a private network, configure secure connectivity across your containerized and private (or on-premises) environments. For example, your Designer integration might include an action that puts a message on an on-premises IBM® MQ queue, or your Toolkit integration might contain a message flow that interacts with an SAP Gateway OData service in a private network. To connect to an application on a private network, create a private network connection, then download and configure a secure agent.

Availability: These instructions for connecting to a private network apply only to App Connect Designer instances at version 12.0.10.0-r3, which were created by using IBM App Connect Operator 11.1.0 or later.

Restriction: Private network connections are not supported in Kubernetes environments.

About this task

You enable access to a private network by using a switch server to route data, and a secure agent to connect to endpoints on the private network. The switch server runs in your cluster, and IBM App Connect provides a secure agent for you to run on your computer.

To begin, you create a private network connection in your Dashboard instance. To configure this connection, you download the App Connect secure agent and a configuration file (switchclient.json). Update the configuration file with endpoint information (including host, port, and certificates) for connecting to one or more applications in your private network. The switchclient.json file also supplies the switch server location, and certificates that are needed to securely communicate with the switch server.

Finally, start the secure agent by running a command with a parameter that points to the location of your updated switchclient.json file.

When you deploy a Designer integration from the App Connect Dashboard, any account (of type Accounts) that you set up to connect to the private network must include the name of the private network connection so that the flow can use it for secure connectivity. For Toolkit integrations, you set up secure connectivity by configuring SSH port forwarding from a local port to the remote port (and host ) in the private network.

Tip: You can also configure your flows in App Connect Designer to connect to a private network. For more information, see Connecting to a private network from App Connect Designer.

Creating a switch server
Configuring a private network connection
Connecting your integration to applications in the private network
Updating your private network connections or deleting a private network connection

Creating a switch server

To configure secure connectivity between your containerized environment and your private network, you need a switch server in your cluster.

About this task

Use the same switch server with your App Connect Designer and App Connect Dashboard instances in your namespace.

Note: Creating a switch server is a one-time task.

Procedure

To create a switch server, complete the following steps:

From your cluster, create a switch server and link it to your App Connect Dashboard instance.

If you do not already have a switch server in the same namespace as your App Connect Dashboard instance, create a switch server as described in Creating an instance.
Configure the App Connect Dashboard instance to use this switch server. To do so, set the spec.switchServer.name setting in the Dashboard custom resource (CR) to the switch server name (that is, the metadata.name value in the switch server CR), as shown in the following example.
```
apiVersion: appconnect.ibm.com/v1beta1
kind: Dashboard
...
spec:
  switchServer:
    name: default
...
```
You can apply the spec.switchServer.name setting while creating the Dashboard instance or by updating its CR settings as described in Creating an instance and Updating the custom resource settings for an instance.

When you create a switch server, the following changes are applied to your cluster:

A Private network connections icon () and page are added by default to your App Connect Dashboard instance. (You might need to refresh your browser window or tab to view the icon for this page in the navigation pane.) You can use the Private network connections page to set up the configuration that is required to run the secure agent, as described later.

If an App Connect Designer instance with a spec.switchServer.name setting exists in the same namespace, the Private network connections page is also added to this instance.
A configuration object of type Private Network Agent, which is named switchServerName-privatenetworkagent, is created by default.
Configuration objects of type Agentx (named switchServerName-agentx) and type AgentA (named switchServerName-agenta) are also created by default for callable flow and remote administration connectivity. For more information about these configuration objects, see Agentx type and AgentA type.

You can see these configuration objects in the Configuration page in the App Connect Dashboard.

For connectors that support private network connections, a Private network connection field is also added to the connection fields that you complete when creating a connector account to use in your flows or Designer integrations.

What to do next

Configure a private network connection.

Configuring a private network connection

You configure a private network connection between a Designer or Toolkit integration in your cluster and an application in a private network by downloading the App Connect secure agent and its configuration file (switchclient.json) from your Dashboard instance, configuring the application endpoints in the file, and then starting the secure agent.

About this task

Private network connections are shared across App Connect Designer and App Connect Dashboard instances in the same namespace, and are visible on the Private network connections page in both instances. If you configure a secure agent by using the secure agent file and the switchclient.json file that you download from the App Connect Dashboard, you can also use the same secure agent for your flows in App Connect Designer.

A logical approach for configuring private network connections is as follows:

If you are using both App Connect Designer and the Toolkit to develop flows that you will later deploy as integration servers or integration runtimes from the Dashboard, configure the private network connection from the Private network connections page in Designer.
If you are developing only Toolkit flows that you will later deploy as integration servers or integration runtimes from the Dashboard, configure the private network connection from the Private network connections page in the Dashboard.
For simplicity, use a single private network connection and secure agent to configure connectivity to your private network. You can either use the default private network connection on the Private network connections page or create another.
Alternatively, you can create multiple private network connections from the Private network connections page to run multiple secure agents. You might want to do so if you want to maintain separate groupings of endpoint information.
You can define multiple endpoints in the switchclient.json file that you use to configure the secure agent. If you need to specify endpoint information for new connections to your private network, you can update the switchclient.json file in the directory where you saved it.

Procedure

To configure a private network connection, complete the following steps:

From your App Connect Dashboard instance, click Private network connections in the navigation pane to open the Private network connections page.

On initial access, only the default private network connection is displayed. If you have previously created any private network connections in either App Connect Designer or the App Connect Dashboard, they are also listed.

The default private network connection is automatically created when you create the switch server and is named switchServerName-privatenetworkagent. You can use this private network connection to set up a secure connection, or you can create another private network connection and use that instead. If you want to use the default private network connection, you can skip step 2.
Optional: To create a private network connection, click New.

A private network connection with a generated name of pnc-ddd-timestamp (for example, pnc-thu-21-dec-2023-15-12-20-gmt-444) is created and added to the table.

Tip: The new private network connection is added to the Private network connections page in both App Connect Designer and the App Connect Dashboard. A corresponding configuration object of type Private Network Agent is also created with the name pnagent-agentID; for example, pnagent-37c32e94-f488-407f-8917-0cebe89c5920.
Open the Actions menu for the private network connection and click View setup instructions.
In the Set up secure connectivity panel, ensure that the Private networks tab is selected.
Expand the first step of the instructions, select your operating system, then click Download the secure agent.
Read and accept the license by selecting I accept the license then clicking Accept.

The secure agent is downloaded in a compressed archive that is called secureagent-os_x64_version, where os is the operating system. For example, secureagent-win_x64_12-0-27.zip or secureagent-linux_x64_12-0-27.tgz.
Extract the contents of the secureagent archive to a directory that you will run the secure agent from; for example /appconnect_pnc/secureagent or C:\appconnect_pnc\secureagent. The extracted content includes a secureagent executable file.
Expand the second step of the instructions, then click Download the configuration.

The downloaded secure agent configuration file is called switchclient.json. Copy the file from its download location to a working directory. You might find it useful to copy the file to the same directory where you extracted the contents of the secureagent archive; for example, /appconnect_pnc or C:\appconnect_pnc.

To configure one or more application endpoints in the private network that you want to connect to, update the switchclient.json file as follows. If necessary, work an administrator who is authorized to configure security for the private network and can provide connection details for the on-premises applications and systems.

Open the switchclient.json file in the working directory.

The file contents are similar to this example. You can update the endpoints array, but do not change the switch object, which contains the switch server URL and the certificates that the secure agent uses to communicate with the switch server.

{
  "id": "37c32e94-f488-407f-8917-0cebe89c5920",
  "admin": "enabled",
  "callableFlows": "enabled",
  "endpoints": [
    {
      "name": "",
      "hostname": "",
      "port": 0,
      "useTLS": false,
      "certs": {
        "key": "",
        "cert": "",
        "ca": [
          ""
        ],
        "rejectUnauthorized": true
      }
    }
  ],
  "switch": {
    "url": "wss://default-switch-ace-fiona.apps.acecc-shared-1110-cd-414-amd64.abc.com:443",
    "certs": {
      "ca": [
        "-----BEGIN CERTIFICATE-----\nxxx\n-----END CERTIFICATE-----\n"
      ],
      "cert": "-----BEGIN CERTIFICATE-----\nyyy\n-----END CERTIFICATE-----\n",
      "key": "-----BEGIN PRIVATE KEY-----\nzzz\n-----END PRIVATE KEY-----\n",
      "rejectUnauthorized": true
    }
  },
  "displayName": "pnc-thu-21-dec-2023-15-12-20-gmt-444"
}

Note: The id entry is omitted and displayName is blank if you downloaded the switchclient.json file for the default private network connection named switchServerName-privatenetworkagent.

Set the admin and callableFlows values to disabled. These fields need to be enabled only if you are configuring remote administration or callable flows.
```
...
  "admin": "disabled",
  "callableFlows": "disabled",
...
```

Add an endpoint object to the endpoints array for each connection to an application. Set name to a descriptive name, hostname to a hostname or IP address, port to a port number, and optionally configure TLS as described in the steps that follow. Endpoints that use HTTP and HTTPS are supported.

Example of two endpoint definitions within the endpoints array

  "endpoints": [
    {
      "name": "My private endpoint",
      "hostname": "myhostname",
      "port": 88888,
      "useTLS": false,
      "certs": {
        "key": "",
        "cert": "",
        "ca": [
          ""
        ],
        "rejectUnauthorized": true
      }
    }
    {
      "name": "Another private endpoint",
      "hostname": "anotherhostname",
      "port": 1234,
      "useTLS": false,
      "certs": {
        "key": "",
        "cert": "",
        "ca": [
          ""
        ],
        "rejectUnauthorized": true
      }
    }
  ],

If the communication between the secure agent and the application in your private network uses the HTTP protocol without encryption, specify a hostname and port, and set useTLS to false.

  "endpoints": [
    {
      "name": "Acme Secure service",
      "hostname": "localhost",
      "port": 88888,
      "useTLS": false,
      "certs": {
        "key": "",
        "cert": "",
        "ca": [
          ""
        ],
        "rejectUnauthorized": true
      }
    }
  ],

If the application uses encrypted transport (with the HTTPS or TLS protocol), specify a hostname and port, and set useTLS to true. You do not need to complete the certs section if the application serves a certificate from a well-known certificate authority.

  "endpoints": [
    {
      "name": "Acme Secure service",
      "hostname": "localhost",
      "port": 8888,
      "useTLS": true,
      "certs": {
        "key": "",
        "cert": "",
        "ca": [
          ""
        ],
        "rejectUnauthorized": true
      }
    }
  ],

If communication between the secure agent and the application requires mutual authentication, provide the public certificate (from a certs.cert file) and the private key (from a certs.key file), which the secure agent will use. The certificates can be self-signed or supplied by a certificate authority (CA). You can use tools such as keytool or OpenSSL to generate the certificate and key if required.

  "endpoints": [
    {
      "name": "Acme Secure service",
      "hostname": "localhost",
      "port": 8888,
      "useTLS": true,
      "certs": {
        "key": "-----BEGIN PRIVATE KEY-----\nYyY\nYyY\nYyY\nYyY\n-----END PRIVATE KEY-----\n",
        "cert": "-----BEGIN CERTIFICATE-----\nXxX\nXxX\nXxX\nXxX\n-----END CERTIFICATE-----\n",
        "ca": [
          ""
        ],
        "rejectUnauthorized": true
      }
    }
  ],

If the application serves a certificate from a less common certificate authority, either provide one or more CA certificates, or stop verification of the application’s certificate.

To provide a CA certificate or list of certificates (from a certs.ca file), provide the certificate details in the certs.ca field.

  "endpoints": [
    {
      "name": "Acme Secure service",
      "hostname": "localhost",
      "port": 8888,
      "useTLS": true,
      "certs": {
        "key": "",
        "cert": "",
        "ca": [
          "-----BEGIN CERTIFICATE-----\nZzZ\nZzZ\nZzZ\nZzZ\n-----END CERTIFICATE-----\n"
        ],
        "rejectUnauthorized": true
      }
    }
  ],

To stop verification of the application's certificate, set certs.rejectUnauthorized to false.

  "endpoints": [
    {
      "name": "Acme Secure service",
      "hostname": "localhost",
      "port": 8888,
      "useTLS": true,
      "certs": {
        "key": "",
        "cert": "",
        "ca": [
          ""
        ],
        "rejectUnauthorized": false
      }
    }
  ],

Save the switchclient.json file.

Use the command line to start the secure agent.

Change to the directory where you extracted the secure agent.
Linux® example:
```
cd /appconnect_pnc/secureagent
```
Windows example:
```
cd C:\appconnect_pnc\secureagent
```
To start the secure agent, run the secureagent command, where pathToConfigurationFile is the location of the switchclient.json file (excluding the filename) and pathToOutputLogDirectory is a path for the logs.
- Linux:
```
./secureagent -c pathToConfigurationFile -l pathToOutputLogDirectory
```
  Example:
```
./secureagent -c /appconnect_pnc -l /appconnect_pnc
```
- Windows:
```
secureagent -c pathToConfigurationFile -l pathToOutputLogDirectory
```
  Example:
```
secureagent -c C:\appconnect_pnc -l C:\appconnect_pnc
```
App Connect creates a folder with the name logs at your chosen location; for example, /appconnect_pnc/logs or C:\appconnect_pnc\logs.

Note: The first time that you start the secure agent, you are prompted to read and accept the license. You can find the license in the downloaded secure agent file in the license folder. The license is provided in multiple languages. For example, the English version is LA_en. After you read the license, accept it on the command line by typing yes.

When the secure agent starts, you see output that is similar to this, with a message (SwitchClient - All agents started) that confirms the agent is running.

[2023-12-22T20:35:00.191Z] [WARN] SecureAgentCLI - Certificate validation has been skipped because openssl is not available.
[2023-12-22T20:35:00.199] [INFO] SwitchClient - IBM App Connect Switch Client 9.1.11 | win32_x64
[2023-12-22T20:35:00.200] [INFO] SwitchClientRunner - Switch client configuration:
[2023-12-22T20:35:00.200] [INFO] SwitchClientRunner - {
  "id": "37c32e94-f488-407f-8917-0cebe89c5920",
  "admin": "disabled",
  "callableFlows": "disabled",
  "endpoints": [
    {
      "name": "test service",
      "hostname": "localhost",
      "port": 8888,
      "useTLS": false,
      "certs": {
        "key": "",
        "cert": "",
        "ca": [
          ""
        ],
        "rejectUnauthorized": true
      }
    }
  ],
  "switch": {
    "url": "wss://default-switch-ace-fiona.apps.acecc-shared-1110-cd-414-amd64.abc.com:443",
    "certs": {
      "ca": [
        "-----BEGIN CERTIFICATE-----\nxxx\n-----END CERTIFICATE-----\n"
      ],
      "cert": "-----BEGIN CERTIFICATE-----\nyyy\n-----END CERTIFICATE-----\n",
      "key": "-----BEGIN PRIVATE KEY-----\nzzz\n-----END PRIVATE KEY-----\n",
      "rejectUnauthorized": true
    }
  },
  "displayName": "pnc-thu-21-dec-2023-15-12-20-gmt-444"
}
[2023-12-22T20:35:00.201] [INFO] SwitchClientRunner - Starting switchclient with config folder: 'C:\appconnect_pnc'
[2023-12-22T20:35:01.146] [INFO] SwitchClient - AgentP started
[2023-12-22T20:35:01.146] [INFO] SwitchClientRunner - AgentP successfully connected to switch(es) [
  'wss://default-switch-ace-fiona.apps.acecc-shared-1110-cd-414-amd64.abc.com:443'
]
[2023-12-22T20:35:01.147] [INFO] SwitchClient - All agents started

What to do next

Associate this private network connection with connector accounts (in Designer flows or Designer integrations) that need to connect to your private network.

Connecting your integration to applications in the private network

To deploy an integration that uses the private network connection to access one or more applications in your private network, you need to create configuration objects that can be applied to the integration. The configuration types depend on whether you are deploying a Designer or Toolkit integration.

Integrations that connect to applications on the private network will work only while the secure agent is running.

Procedure

To configure an integration to connect to a private network, complete the following steps from your App Connect Dashboard instance:

Open the Private network connections page by clicking Private network connections in the navigation pane. Then, copy the name of the private network agent that you configured earlier (for example, default-privatenetworkagent) and paste it into a text editor. You will need to specify this value later.
While deploying the BAR file for your Designer or Toolkit integration to an integration server or integration runtime, create the required configuration objects.
- If you are deploying a Designer integration, use the Configuration page or Configuration view to create a configuration object of type Accounts, which contains connection details for each connector that is used in the exported flow. All connectors that support private network connections include a Private network connection field in the connection fields that are provided for setting up accounts.
  1. When you add an account for a connector that needs to interact with the private network, use the Private network connection field to specify the name of the private network connection, which you copied in step 1.
    The following example shows a completed Private network connection field for an HTTP connector account.
  2. After you create this configuration object, ensure that you select its checkbox in the Configurations table to indicate that you want to apply it to your integration.
    
    Also select the configuration object of type Private Network Agent, which is associated with your private network connection. (This configuration object was created by default when the connection was created. If you are using the default private network connection named switchServerName-privatenetworkagent, the corresponding configuration object also has the same name.) Port forwarding is configured by default to tunnel connections from a local listening port to the remote port on which the remote host listens.
- If you are deploying a Toolkit integration, use the Configuration page or Configuration view to create a configuration object of type Private Network Agent. You need this configuration object to set up port forwarding to tunnel connections from a local listening port to the remote port on which the remote host listens. For more information, see Private Network Agent type.
  
  After you create this configuration object, ensure that you select its checkbox in the Configurations table to indicate that you want to apply it to your integration.
  
  You might also need to add the local listening port to any other configuration object that specifies values for the remote host and port. Also select this configuration object to apply it to your integration. To see examples of how to set up port forwarding, see Connecting IBM App Connect to an IBM Db2 database in a private network and Connecting IBM App Connect to an IBM MQ queue manager in a private network.
Complete the deployment steps for the integration server or integration runtime. Requests are forwarded through the local port to the switch server, secure agent, and on to the remote host.

Tip: Based on the type of integration that you deployed, you can use the built-in test function to confirm that you can successfully connect to the private network when the deployment completes. For more information, see Testing the deployed integration.

Updating your private network connections or deleting a private network connection

You can update the endpoint definitions that are configured for the secure agent. You can also delete a private network connection if it's longer required.

Endpoint definitions are stored in the switchclient.json file that you reference when you run the command to start the secure agent.

Procedure

If you need to add, update, or remove endpoint information that is configured for your private network connections, complete the following steps:
1. Copy the switchclient.json file from its current location to a temporary location on your computer. Then, update the endpoints array in the file to update existing values, or to add or remove endpoint objects. Save your changes.
2. Replace the existing switchclient.json file (which the secure agent uses) with the updated file.
You can delete a private network connection from the Private network connections page by clicking the Delete option in the Actions menu, and then confirming the deletion.

The private network connection is deleted from the Private network connections page in your App Connect Designer and App Connect Dashboard instance:s, and you can no longer use this connection to connect to a private network if it's referenced in a flow or integration. The corresponding configuration object is also deleted.

Note: You cannot delete the default private network connection named switchServerName-privatenetworkagent.