Client-authenticated Transport Layer Security with the i2 Connect gateway

Before you begin

In a production deployment you should configure i2 Analyze to connect to your connector using client-authenticated TLS communication. To do so, your connector and i2 Analyze must trust the certificates that they receive during the TLS handshake process. In a production environment, the certificates must be signed by a trusted certificate authority. For more information about client authenticated SSL, see Client-authenticated TLS handshake.

The following diagram shows the keystores and truststores that are required for Liberty and the connector.

The Liberty server requires a keystore file and a truststore file. Your connector can use any implementation for its keystore and truststore. The certificates in each truststore must trust the certificates received from the corresponding keystore.

The certificates that are required are as follows, where certificate authority (CA) X issues the certificates to the connector (the server) and Liberty (the client):

Connector

Each connector requires:

• Keystore contents:

  • The personal certificate issued to the connector by CA X

  • The connector's private key

• Truststore contents:

  • The CA certificate for CA X

Open Liberty

Each Liberty server requires:

• Keystore contents:

  • The personal certificate issued to Liberty by CA X

  • Liberty's private key

• Truststore contents:

  • The CA certificate for CA X

About this task

After you have created and populated the keystores and truststores for the connector and Liberty, you must configure Liberty to use TLS to communicate with any connectors.

The following steps explain the process of updating the i2 Analyze configuration with the location of a keystore and truststore to use, and the passwords that are used to access the certificates that are contained within them.

To configure the example connector to use client-authenticated TLS, and for examples of how to create keystores, truststores, and certificates for Liberty, follow the instructions in Securing the example connector.

Procedure

1. In an XML editor, open the toolkit\configuration\environment\topology.xml file.

   1. Add the <key-stores> element as a child of the <application> element. Then, add child <key-store> elements.

      For your keystore, specify the type as key-store, and file as the full path to your keystore. For your truststore, specify the type as trust-store, and file as the full path to your truststore.

      For example, add the attribute as highlighted in the following code:

      <application http-server-host="true"
          name="opal-server" host-name="<hostname>">
        ...
        <key-stores>
          <key-store type="key-store"
              file="C:/i2/i2analyze/i2-liberty-keystore.jks"/>
          <key-store type="trust-store"
              file="C:/i2/i2analyze/i2-liberty-truststore.jks"/>
        </key-stores>
        ...
      </application>

   2. Update the base-url attribute of any connectors using TLS to use the HTTPS protocol.

      For example:

      <connectors>
        <connector id="example-connector" name="Example" 
            base-url="https://localhost:3700/"/>
        </connector>

      Note: Ensure that the hostname that is used in the base URL matches the common name on the certificate of the connector.

2. Specify the keystore and truststore passwords in the credentials file.

   1. In a text editor, open the toolkit\configuration\environment\credentials.properties file.

   2. Enter the password for the keystore and truststore that you specified in the topology.xml file.

      ssl.keystore.password=<password>
      ssl.truststore.password=<password>

3. Redeploy i2 Analyze to update the application with your changes.

   1. In a command prompt, navigate to the toolkit\scripts directory.

   2. Stop Liberty:

      setup -t stopLiberty

   3. Update the i2 Analyze application:

      setup -t deployLiberty

   4. Start Liberty:

      setup -t startLiberty

What to do next

You can create your own connectors to use with the deployment of i2 Analyze, when you create your own connector you can implement security that conforms to the security required by the i2 Connect gateway. For more information about creating your own connectors, see i2 Analyze and i2 Connect.

When you use a connector configured for TLS communication, you should not see any warnings displayed in Analyst's Notebook.