Connecting to a private network from the App Connect Dashboard (in IBM App Connect Operator 6.2.0 through 11.0.x)

To configure secure connectivity between your containerized environment and your private network, you need a switch server in your cluster, and an IBM App Connect Enterprise integration server that runs a secure agent.

To create a switch server and an IBM App Connect Enterprise integration server, complete the following steps:

1. From your cluster, create a switch server and link it to your App Connect Dashboard instance.
   1. 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.
   2. 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.

2. From your IBM App Connect Enterprise 12.0.7.0 or later environment, create an independent integration server.
   1. Open the App Connect Enterprise command environment.
      • Windows: From the Start menu, expand IBM App Connect Enterprise xx.0.x.x Developer Edition (where xx.0.x.x denotes a version such as 12.0.7.0), then click IBM App Connect Enterprise Console.
      • Linux®: Locate and source the mqsiprofile.sh script in the directory where you installed App Connect Enterprise.

        source install_dir/server/bin/mqsiprofile

   2. To create a work directory for your integration server, run the mqsicreateworkdir command and specify the full path to the directory that you want to create.

      For example, on Windows, you can run the following command to create a C:\appconnectpnc\myswitchclient work directory.

      mqsicreateworkdir C:\appconnectpnc\myswitchclient

      The mqsicreateworkdir command creates the specified work directory and you see the following output.

      mqsicreateworkdir: Copying sample server.config.yaml to work directory
              1 file(s) copied.
      Successful command completion.

      The work directory contains a server.conf.yaml configuration file with default settings for your integration server, and subdirectories that the integration server will use when it's running. For more information, see mqsicreateworkdir command in the App Connect Enterprise documentation.

You configure a private network connection between a Designer or Toolkit integration in your cluster and an application in a private network by using a switchclient.json configuration file to set up an IBM App Connect Enterprise integration server with a running secure agent.

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

1. From your App Connect Dashboard instance, download the switch client configuration file for the private network connection that you want to configure.
   1. 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 1.b.

   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-fri-22-dec-2023-18-30-13-gmt-837) is created and added to the table. (In earlier versions, the name is generated as pnagent-agentID.)

      

      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-b53ae000-7885-440a-8817-da249f930b61.
   3. Download the switch client configuration file for the default or the newly created private network connection and transfer this file to the computer where you created the IBM App Connect Enterprise integration server earlier.
      1. Open the Actions menu for the private network connection and click View setup instructions.
      2. From the Connecting to a private network panel, click Download the configuration to download a switchclient.json file to a default or configured download location. You can skip step 1 in the instructions because you have already created the integration server.

      
2. 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.
   1. Open the downloaded switchclient.json file.
      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": "b53ae000-7885-440a-8817-da249f930b61",
        "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-cd-412-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-fri-22-dec-2023-18-30-13-gmt-837"
      }

      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.

      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
              }
            }
          ],

   2. 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
            }
          }
        ],

   3. 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
            }
          }
        ],

   4. 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
            }
          }
        ],

   5. 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
              }
            }
          ],

3. Add the updated switchclient.json file to your integration server's work directory and then start your integration server.
   1. Move the updated switchclient.json file into the following location in the integration server's work directory: workdir/config/switch. (Create the switch directory if it doesn't already exist.)
   2. To start your integration server, run the IntegrationServer command in an App Connect Enterprise command environment.

      For example, on Windows, you can run the command as follows, where C:\appconnectpnc\myswitchclient represents the integration server's work directory.

      IntegrationServer --work-dir C:\appconnectpnc\myswitchclient

      For more information, see IntegrationServer command in the App Connect Enterprise documentation.

      Check the output for a message confirming that the switchclient component (that is, your App Connect Enterprise integration server) has started. You should also see messages indicating that a connection has been established to the switch server whose URL is referenced within the switch object in the switchclient.json file.

      2023-12-22 18:44:11.273919: BIP1990I: Integration server 'myswitchclient' starting initialization; version '12.0.7.0' (64-bit)
      2023-12-09 2:44:11.330181: BIP9905I: Initializing resource managers.
      2023-12-2 18:44:35.061760: BIP9906I: Reading deployed resources.
      2023-12-2 18:44:41.723708: BIP2866I: IBM App Connect Enterprise administration security is inactive.
      2023-12-22 18:44:41.737276: BIP3132I: The HTTP Listener has started listening on port '7600' for 'RestAdmin http' connections.
      2023-12-22 18:44:41.746416: BIP1991I: Integration server has finished initialization.
      2023-12-22 18:44:41.764688: BIP2206I: The integration server component 'switchclient' has been started.
      2023-12-22 18:44:43.127132: BIP6469I: The secure connectivity agent for on-premises systems has established a connection to the Switch server with URL 'wss://default-switch-ace-fiona.apps.acecc-shared-cd-412-amd64.abc.com:443'.
      2023-12-22 18:44:48.300804: BIP6485I: The connection agent for remote administration has established a connection to the Switch server with URL 'wss://default-switch-ace-fiona.apps.acecc-shared-cd-412-amd64.abc.com:443'.
      2023-12-22 18:44:48.309512: BIP6450I: The connection agent for remote callable flows has established a connection to the Switch server with URL 'wss://default-switch-ace-fiona.apps.acecc-shared-cd-412-amd64.abc.com:443'.
      2023-12-22 18:44:48.318212: BIP6484I: The connection agent for remote administration successfully registered using App Connect agent identifier 'b53ae000-7885-440a-8817-da249f930b61'.

   The secure agent now runs in your integration server.

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

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

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

• 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 workdir/config/switch/switchclient.json file in your integration server's work directory to a temporary location on your computer. Then, update the endpoints array in the file as required, and save your updates.
  2. Delete the existing workdir/config/switch/switchclient.json file in your integration server's work directory.
  3. Wait for approximately 5 seconds and then add your updated switchclient.json file to workdir/config/switch.

     When you delete the file, the connections to the switch server are terminated and the secure agent is stopped. The connections are re-established and the secure agent is restarted when you add your updated file to workdir/config/switch. You can see associated messages in the App Connect Enterprise command environment for the integration server.

     2023-06-14 09:13:14.798295: BIP6470I: The secure connectivity agent for on-premises systems has terminated the connection to the Switch server with URL 'wss://default-switch-ace-fiona.apps.acecc-shared-cd-412-amd64.abc.com:443'.
     2023-06-14 09:13:14.807374: BIP6451I: The connection agent for remote callable flows has terminated the connection to the Switch server with URL 'wss://default-switch-ace-fiona.apps.acecc-shared-cd-412-amd64.abc.com:443'.
     2023-06-14 09:13:14.816000: BIP6486I: The connection agent for remote administration has terminated the connection to the Switch server with URL 'wss://default-switch-ace-fiona.apps.acecc-shared-cd-412-amd64.abc.com:443'.
     2023-06-14 09:13:14.823165: BIP2207I: The integration server component 'switchclient' has been stopped.
     2023-06-14 09:14:30.716386: BIP6450I: The connection agent for remote callable flows has established a connection to the Switch server with URL 'wss://default-switch-ace-fiona.apps.acecc-shared-cd-412-amd64.abc.com:443'.
     2023-06-14 09:14:30.726376: BIP6469I: The secure connectivity agent for on-premises systems has established a connection to the Switch server with URL 'wss://default-switch-ace-fiona.apps.acecc-shared-cd-412-amd64.abc.com:443'.
     2023-06-14 09:14:30.734416: BIP6485I: The connection agent for remote administration has established a connection to the Switch server with URL 'wss://default-switch-ace-fiona.apps.acecc-shared-cd-412-amd64.abc.com:443'.
     2023-06-14 09:14:30.741004: BIP2206I: The integration server component 'switchclient' has been started.
     2023-06-14 09:14:30.741714: BIP6484I: The connection agent for remote administration successfully registered using App Connect agent identifier '13453796-b219-4a78-a3d9-afa836d67169'.

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