Connecting to a private network

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

1. In IBM App Connect Enterprise as a Service, expand Connect and click Private networks.
   If you have existing private network connections, they’re listed.
2. Optional: By default, App Connect Enterprise as a Service allows connections over the public internet. You can use the Public connections switch to disable public connections for your instance.
   For example, if you disable public connections, no-one can call an API flow in your instance over the public internet. Disabling public connections doesn't affect private network connections that use private network agents. Enabling or disabling public connections can take several minutes to take effect.
3. You can use an existing private network connection, or create one by clicking Create.
4. Optional: Enter a name for your private network connection.
   The default name includes the date and time when you created the private network connection but you can rename it to something more memorable. The name can include lowercase alphanumeric characters (a-z, 0-9), periods (.), and hyphens (-). It must start and end with a lowercase alphanumeric character.
5. In the Actions menu for the private network connection, click View setup instructions, and go to the Private networks tab.
6. Expand the first step of the instructions, select your operating system, then click Download the secure agent.
7. 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.

8. Extract the contents of the secureagent archive.
9. Expand the second step of the instructions, then click Download the configuration.
   The downloaded secure agent configuration file (as seen in the following example) is called switchclient.json.

   {​ 
     "admin": "enabled",
     "callableFlows": "enabled",
     "endpoints": [
       {
         "name": "",
         "hostname": "",
         "port": 0,
         "useTLS": false,
         "certs": {
           "key": "",
           "cert": "",
           "ca": [
             ""
           ],
           "rejectUnauthorized": true
         }
       }],​
     "switch": {​
       "url": "wss://default-switch-server-switch-ab0cdef1ghi.switch.p-vir-d1.appconnect.ibmappdomain.cloud:443",​
       "certs": {​
         "key": "-----BEGIN PRIVATE KEY-----\nzzz\n-----END PRIVATE KEY-----\n",​
         "cert": "-----BEGIN CERTIFICATE-----\nyyy\n-----END CERTIFICATE-----\n",​
         "ca": [​
           "-----BEGIN CERTIFICATE-----\nxxx\n-----END CERTIFICATE-----\n"​
         ],​
         "rejectUnauthorized": true​
       }​
     }​,
     "displayName": "yourpncname"
   }​

10. To configure the application endpoints that you want to connect to, open the downloaded switchclient.json file and make the following changes that apply to your security needs.
    • Add an endpoint object to the endpoints array for each connection to an application and remove the certs section, as shown in the following example. (You also need to remove the comma after "useTLS": false.)

      "endpoints": [
          {
            "name": "endpoint1",
            "hostname": "localhost",
            "port": 8888,
            "useTLS": false
          }
        ],

      With this basic configuration, communication between the secure agent and the application in your network uses the HTTP protocol and isn’t encrypted.

    • If the endpoint application uses the TLS or HTTPS protocol, set useTLS to true, as shown in the following example.

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

      With this configuration, your application uses encrypted transport (HTTPS or TLS). If your application serves a certificate from a well-known certificate authority, this configuration is the only TLS or certificate setting that you need.

    • If communication between the secure agent and the application requires mutual authentication, provide the certificate and the private key that the secure agent uses, as shown in the following example. The certificate must be in a certs.cert file and the private key must be in a certs.key file. The certificates can be self-signed or supplied by a certificate authority.

      "endpoints": [
          {
            "name": "endpoint1",
            "hostname": "localhost",
            "port": 8888,
            "useTLS": true,
          "certs": {
              "key": "-----BEGIN PRIVATE KEY-----\nYyY\nUuU\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 certificate authority certificate or list of certificates (certs.ca), add the following configuration.

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

      Alternatively, to stop verification of the application’s certificate, set certs.rejectUnauthorized to false.

11. Use the command line to start the secure agent.
    1. Change to the directory where you extracted the secure agent.
       For example, on Windows, enter the command cd C:\secureAgent\secureagent-win_x64_12-0-7.
    2. To start the secure agent, run the secureagent command.
       On Windows, run the following command:

       secureagent -c pathToConfigurationFile -l pathToOutputLogDirectory 

       For example, secureagent -c C:\secureAgent -l C:\secureAgent

       On Linux®, run the following command:

       ./secureagent -c pathToConfigurationFile -l pathToOutputLogDirectory 

       For example, ./secureagent -c /secureAgent -l /secureAgent

       App Connect creates a folder with the name logs at your chosen location.

       Note: The first time that you start the secure agent, you're 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".

Results

When the secure agent starts, you see the message SwitchClient - All agents started. Your App Connect private network connection is now available to select in the Private network connection field when you connect to your endpoint. The following example shows the Private network connection field when you connect an HTTP node in your flow.

1. In App Connect Enterprise 12.0.7.0 or later, create an integration server by running the mqsicreateworkdir command in the App Connect Enterprise command environment.
   This command creates a work directory for your integration server that contains a default configuration file called server.conf.yaml. This YAML file contains the default settings for your new integration server. (For more information, see mqsicreateworkdir command in the App Connect Enterprise documentation.)
2. Configure the App Connect Enterprise integration server to be a secure agent.
   1. In IBM App Connect Enterprise as a Service, expand Connect in the navigation panel, click Private networks, then click Create.
   2. Open the menu next to the new private network connection, then click View setup instructions.
   3. In the Download the secure agent configuration step, select your operating system, then click Download the configuration.
      The configuration file for the secure agent (switchclient.json) is downloaded to a location on your computer.
   4. Edit the switchclient.json file to add the hostname (or IP address) and port of the endpoint application to the endpoints array.
      The following example shows endpoint details for an IBM MQ queue manager.

      {
        "id": "fbda61eb-0e17-4bd2-a61d-9d202c1b2303",
        "admin": "enabled",
        "callableFlow": "enabled",
        "endpoints": [
          {
            "name": "My MQ endpoint descriptive name",
            "hostname": "192.0.2.24",
            "port": 1414,
            "useTLS": false,
            "certs": {
              "key": "",
              "cert": "",
              "ca": [
                ""
              ],
              "rejectUnauthorized": true
            }
          }
        ],
        "switch": {
          "url": "wss://default-switch-server-switch-abcdefgh1jg.apps.appc-c-vir-d1.vz8y.p1.abc.com:443",
          "certs": {
            "key": "-----BEGIN PRIVATE KEY-----\nxxx\n-----END PRIVATE KEY-----\n",
            "cert": "-----BEGIN CERTIFICATE-----\nyyy\n-----END CERTIFICATE-----\n",
            "ca": [
              "-----BEGIN CERTIFICATE-----\nzzz\n-----END CERTIFICATE-----\n"
            ],
            "rejectUnauthorized": true
          }
        },
        "displayName": "pnc-wed-14-jun-2023-07-25-14-gmt-553"
      }

   5. Move the updated switchclient.json file to the workdir/config/switch directory of the App Connect Enterprise integration server that you created earlier.
   6. Start the App Connect Enterprise integration server.
   The App Connect Enterprise integration server is now connected to the switch server in your IBM App Connect Enterprise as a Service instance.
3. Configure port forwarding for your Toolkit flow by creating a Private network agent configuration in IBM App Connect Enterprise as a Service.
   Port forwarding redirects connections from a local listening port to the remote port where the endpoint application is listening.
   1. Save a copy of the updated switchclient.json file from the previous step to a temporary location. Make a note of the hostname and port values in this file because you need to add them to the listeners array in a later step.
   2. Edit the file to remove the id, admin, callableFlows, and endpoints sections.
   3. Insert a listeners array directly after the first opening curly bracket in the file.

        "listeners": [{
        "localPort": localPortNumber,
        "remoteHostname": "remoteHost",
        "remotePort": remotePortNumber
      }],

      localPortNumber is a local port number of your choice, through which all connections to the remote port on the private network are forwarded.
      remoteHost is the hostname or IP address of the endpoint application from the pre-edited switchclient.json file.
      remotePortNumber is the port number of the endpoint application from the pre-edited switchclient.json file.
      The following example shows a completed file. In this example, connections to local port 9000 are forwarded to the remote port 1414 on which the endpoint application host 192.0.2.24 listens.

      {
        "listeners": [{
        "localPort": 9000,
        "remoteHostname": "192.0.2.24",
        "remotePort": 1414
      }],
        "switch": {
          "url": "wss://default-switch-server-switch-abcdefgh1jg.apps.appc-c-vir-d1.vz8y.p1.abc.com:443",
          "certs": {
            "key": "-----BEGIN PRIVATE KEY-----\nxxx\n-----END PRIVATE KEY-----\n",
            "cert": "-----BEGIN CERTIFICATE-----\nyyy\n-----END CERTIFICATE-----\n",
            "ca": [
              "-----BEGIN CERTIFICATE-----\nzzz\n-----END CERTIFICATE-----\n"
            ],
            "rejectUnauthorized": true
          }
        },
        "displayName": "pnc-wed-14-jun-2023-07-25-14-gmt-553"
      }

4. Create a Private network agent configuration by using the edited switchclient.json file.
   1. On the Manage page of App Connect, click Configurations, then Create configuration.
   2. In Type, select Private network agent and enter a name for the configuration.
   3. Paste the contents of your switchclient.json into the Private network agent section.
      (For more information, see Private network agent configuration.)
   4. Click Create.
5. Optional: You might need to create more configurations for your Toolkit flow. an mqccdt configuration that contains client-connection channel definitions for the queue manager that the integration runtime needs to connect to. This configuration type requires a JSON CCDT file.
   For example, if your flow connects to an IBM MQ queue manager, you might need to add mqccdt, mqccred.ini, Policy project, and setdbparms.txt configurations.
6. Deploy the BAR file to IBM App Connect Enterprise as a Service by following the instructions in Deploying integrations. In the Configurations section, select the Private network agent configuration and any other configurations that your flow needs.