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

To create flows in App Connect Designer, which interact with applications that run on a private network, configure secure connectivity across your containerized and private (or on-premises) environments by creating a private network connection. For example, your flow might include an HTTP action that sends requests to an HTTP server or endpoint that is hosted on a private network.

Availability: These instructions for connecting to a private network apply only to App Connect Designer instances at version 12.0.7.0-r1 through 12.0.10.0-r2, which were created by using IBM® App Connect Operator 6.2.0 through 11.0.x.
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 configuration file (switchclient.json) that you can use to configure a secure agent that runs on your computer.

To begin, you create a private network connection in your Designer instance, and then download the configuration file that is supplied to configure the connection. Update the 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.

To set up your secure agent, you create an integration server in your IBM App Connect Enterprise on-premises system, and then add the updated switchclient.json file to the integration server's work directory. You complete the setup by starting the integration server, which then runs the secure agent.

To enable an App Connect Designer flow to interact with an application in the private network, include the name of the private network connection in the credentials that you specify when you add an account for connecting to that application. The flow uses the associated secure agent to securely communicate with the private network.

Tip: While deploying an integration server or integration runtime, you can also configure the Designer or Toolkit integration to connect to a private network. For more information, see Connecting to a private network from the App Connect Dashboard.


Creating a switch server and a dedicated integration server to run the secure agent

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.

Before you begin

To create the IBM App Connect Enterprise integration server, you require an installation of App Connect Enterprise 12.0.7.0 or later on premises. If you need to, you can download and install IBM App Connect Enterprise for Developers on your computer. For more information, see Download IBM App Connect Enterprise for Developers and get started with a hands-on experience in the App Connect Enterprise documentation.

About this task

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

Although you can use an independent integration server or an integration node as the switch client, these instructions provide commands for an independent integration server because the setup is simpler. Use this integration server to run the secure agent only, and do not deploy your own flows to it.

Note:

Creating a switch server is a one-time task.

Creating an integration server might also be a one-time task based on your preference. You can choose to create a single integration server to run a secure agent, which can access multiple endpoints that your flows in Designer or your deployed integrations in the Dashboard need to interact with. You can alternatively create and configure multiple integration servers to run separate secure agents.

Procedure

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 Designer instance.
    1. If you do not already have a switch server in the same namespace as your App Connect Designer instance, create a switch server as described in Creating an instance.
    2. Configure the App Connect Designer instance to use this switch server. To do so, set the spec.switchServer.name setting in the Designer 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: DesignerAuthoring
...
spec:
  switchServer:
    name: default
...

      You can apply the spec.switchServer.name setting while creating the Designer instance or by updating its CR settings as described in Creating an instance and Updating the custom resource settings for an instance.

      Tip: If you set the metadata.name value for the switch server to default, the Designer instance is automatically configured to use the switch server even if you do not explicitly specify spec.switchServer.name.

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

    • A Private network connections icon (Private network connections icon) and page are added by default to your App Connect Designer instance. A Callable flows icon (Callable flows icon) and page for configuring callable flow connectivity are also added. (You might need to refresh your browser window or tab to view the icons for these pages 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.
      "Private network connections" page in App Connect Designer

      If an App Connect Dashboard 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.

      You can see these configuration objects in the Configuration page in the App Connect Dashboard. For more information, see Configuration types for integration servers and integration runtimes.

      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.

What to do next

Configure a private network connection that enables the integration server to run a secure agent.

Configuring a private network connection

You configure a private network connection between a flow 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.

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 a switchclient.json file that you download from App Connect Designer, you can also use the same secure agent when you deploy integrations from the App Connect Dashboard.

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 add to the IBM App Connect Enterprise integration server work directory. If you need to specify endpoint information for new connections to your private network, you can update the switchclient.json file in the work directory with these details.

Procedure

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

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

      "Private network connections" page in App Connect Designer

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

      New private network connection in the private network connections 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-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 Actions menu for a private network connection 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.
      "Connecting to a private network" panel
  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.

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

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 flow to applications in the private network

To create a flow that uses the private network connection to access one or more applications in your private network, you need to include the name of the private network connection in the credentials that you specify when you add accounts for connecting to those applications. Connectors that support private network connections include a Private network connection drop-down list in the connection fields that are provided for setting up accounts.

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

Procedure

To configure a flow to connect to a private network, complete the following steps:

  1. From your App Connect Designer instance, create an account for each connector that needs to interact with the private network.
    1. From the Catalog page, locate and click the connector to see additional details.
    2. If this is the first account for the connector, click Connect. Otherwise, open the Account drop-down list and then select Add a new account.
    3. Complete the connection fields. When you get to the Private network connection drop-down list, ensure that you select the name of the private network connection that you configured earlier. This drop-down list is populated with the names of the private network connections from the Private network connections page.
      "Private network connection" drop-down list populated with names of the private network connections
    4. Click Connect.
  2. Create your flow with the required nodes. When you add a node for the connector that needs to interact with the private network, ensure that you select the account that you just created.
    Tip: You can use Try this action or Try this flow ("Try this action" or "Try this flow" icon) to confirm that you can successfully connect to the private network before you start the flow. You can also test the flow after you start it. For more information, see Testing your flows.
  3. Start the flow.

    Requests are forwarded through a system-configured local port to the switch server, secure agent, and on to the remote host.

Updating your private network connections or deleting a private network connection

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

Endpoint definitions are stored in the switchclient.json file in the work directory for the App Connect Enterprise integration server on which the secure agent runs.

Procedure

  • If you need to add, update, or remove endpoint information about 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 to update existing values, or to add or remove endpoint objects. Save your changes.
    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'.
  • To delete a private network connection from the Private network connections page, click the Delete option in the Actions menu, and then confirm the deletion.
    Delete option for a private network connection

    The private network connection is deleted from the Private network connections page in your App Connect Designer and App Connect Dashboard instances, 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.