Enabling SSL for external WebSphere eXtreme Scale (WXS) grids

Enable SSL for an external WebSphere® eXtreme Scale grid by setting up a public key infrastructure, then enabling SSL on the integration server.

Before you begin

Read the concept information in WebSphere eXtreme Scale (WXS) grids and Public key cryptography.

About this task

You can enable SSL for client connections to external WebSphere eXtreme Scale grids. You cannot enable SSL for servers in the embedded WXS grid.

To enable SSL communication, configure the keystore, truststore, passwords, and certificates. To enable server authentication, import the public certificate from the WebSphere eXtreme Scale server into the integration server truststore. If the server requires client authentication, you must also create a private key in the integration server keystore that the WebSphere eXtreme Scale server trusts.

You then modify the server.conf.yaml configuration file for the integration server and set properties to enable SSL and specify the required protocol. You can also nominate a particular key to use if you have more than one. SSL connections can be made only from integration servers that are not hosting catalog or container servers.

The following steps describe how to enable SSL for an external WebSphere eXtreme Scale grid.

Procedure

  1. Set up a public key infrastructure by following the instructions in Setting up a public key infrastructure.
    You can set up the public key infrastructure at integration node or integration server level.

    Connections to external WebSphere eXtreme Scale grids cannot implicitly use public certificates that are located in the JVM cacerts file.

Modify the properties in the server.conf.yaml configuration file for the integration server:

  1. Use a YAML editor to open the server.conf.yaml file.

    You can edit the file by using the built-in YAML editor that is provided in the IBM® App Connect Enterprise Toolkit, either by double-clicking the file in the Application Development view or by right-clicking the file and selecting Open with > YAML editor. If you choose to edit the file by using a plain text editor, ensure that you do not include any tab characters (which are not valid in YAML) and use a YAML validation tool to validate the contents of your file.

    For more information about working with YAML, see http://www.yaml.org/start.html.

  2. Ensure that you are enabling SSL on an integration server that does not host a catalog or container server, by setting the enableCatalogService and enableContainerService properties in the server.conf.yaml configuration file to false.
  3. To enable SSL, set the following properties in the server.conf.yaml file:
    • To enable SSL, set the clientsDefaultToSSL property true.
    • To specify an SSL protocol, set sslProtocol to a value that is recognized by the IBM JSSE2 security provider.
    • If the external grid requires client authentication and you have more than one trusted private key in the integration node keystore, set sslAlias to the appropriate key.
  4. Restart the integration server for the changes to take effect.
  5. Connect to the WebSphere eXtreme Scale grid by following the instructions in Connecting to a WebSphere eXtreme Scale grid.

Results

Keystore, truststore, and protocol settings are verified the first time that a connection is made from the integration server (either to the embedded grid, or for the first remote connection). Errors in the configuration are reported as a warning, and SSL connections are then prohibited. For example, a warning is issued if a keystore file is not found, the file is corrupted, or the keystore password is incorrect.

If you enable SSL and try to connect from an integration server that hosts WebSphere eXtreme Scale server components, the connection fails with a detailed exception message, BIP7144, which explains why the connection failed. If an SSL handshake exception occurs, the message flow fails and the exception message BIP7147 is issued.