Securing the example connector

In a production deployment, you must configure your connectors with client-authenticated TLS communication. You can configure the example connector to communicate with i2 Analyze by using client-authenticated TLS communication.

Before you begin

You must configure your connectors to use client-authenticated TLS communication with i2 Analyze. For more information about configuring security between connectors and i2 Analyze, see Client authenticated Transport Layer Security with the i2 Connect gateway.

About this task

Configure secure communication between Liberty and the example connector that is provided with i2 Analyze. The following steps demonstrate how to create the keystores, truststores, and certificates, then configure i2 Analyze and the example connector to use them.

When you create your own connector, you can implement the security implementation in the same way as used in the example connector, or a different method depending on your requirements.

In a production deployment, you must use a certificate that has been signed by a trusted certificate authority, which the connector can verify. The following steps use a self-signed certificate to demonstrate the functionality.

Procedure

Create a keystore for Liberty that contains a signed certificate that is used to authenticate with the connector.

Create a keystore and a self-signed certificate for Liberty by using the Java keytool utility.
For more information about the Java keytool utility, see keytool - Key and Certificate Management Tool.
1. Open a command prompt and navigate to the i2analyze\deploy\java\bin directory.
2. If you haven't already done so, create the keystore and certificate by running the following command:
```
keytool -genkeypair -alias "libertyKey"
-keystore "C:\i2\i2analyze\i2-liberty-keystore.jks"
-dname "CN=hostname" -keyalg RSA -storepass "libertyKeyStorePassword"
```
  Important: Ensure that you enter values as follows:
  - Set the location of the keystore to the directory that contains the toolkit.
  - Set the value of CN to the hostname of the server that hosts Liberty, as defined in the topology.xml file.
  The password that is specified is used to access the keystore.
3. The example connector implementation requires the Liberty certificate in a base64 encoded format. Export the certificate in base64 encoding by running the following command:
```
keytool -exportcert -alias "libertyKey"
-keystore "C:\i2\i2analyze\i2-liberty-keystore.jks"
-file "C:\i2\i2analyze\i2-liberty-certificate.pem"
-rfc -storepass "libertyKeyStorePassword"
```

Create a keystore for the connector that contains a signed certificate that is used to authenticate with Liberty.

Create a keystore and certificate for the connector by using the Java keytool utility
1. Create the keystore and certificate in PKCS12 format (the default). To create the keystore, run the following command:
```
keytool -genkeypair -alias "connectorKey" -keystore "C:\i2\i2analyze\toolkit\examples\connectors\example-connector\example-connector-keystore.p12" -dname "CN=hostname" -keyalg RSA -storepass "connectorKeyStorePassword"
```
  The password that is specified is used to access the keystore.
  Important: Set the value of CN to the hostname of the server that hosts the connector, as defined in the topology.xml file. By default in the daod-opal example configuration, the value is localhost.
The example connector implementation requires the private key in the PEM format, and the certificate for the connector.
1. Convert the private key from the PKCS12 format to the PEM format. You can use OpenSSL to do this. For more information about OpenSSL see https://www.openssl.org/source/. On Windows you can use easy-rsa to run OpenSSL commands, see https://github.com/OpenVPN/easy-rsa. If you are using OpenSSL, you can run the following command:
```
openssl pkcs12 -in C:/i2/i2analyze/toolkit/examples/connectors/example-connector/example-connector-keystore.p12
-out C:/i2/i2analyze/toolkit/examples/connectors/example-connector/example-connector-key.pem
-nocerts -nodes
```
  When you are prompted for a password, provide the password that you specified when you created the example-connector-keystore.p12 PKCS12 file. In this example, enter connectorKeyPassword.
2. Extract the certificate for the connector by running the following command:
```
keytool -exportcert -alias "connectorKey" -keystore "C:\i2\i2analyze\toolkit\examples\connectors\example-connector\example-connector-keystore.p12" -file "C:\i2\i2analyze\toolkit\examples\connectors\example-connector\example-connector-certificate.pem" -rfc -storepass "connectorKeyStorePassword"
```
  Note: The example-connector-keystore.p12 is not used by the connector and can be removed now that you have extracted the key and certificate.

Create a truststore for Liberty that contains the certificate that is used to trust the certificate that it receives from the connector.

Add the connector's certificate to the Liberty truststore using the Java keytool by running the following command:

keytool -importcert -alias "exampleconnector"
-keystore "C:\i2\i2analyze\i2-liberty-truststore.jks"
-file "C:\i2\i2analyze\toolkit\examples\connectors\example-connector\example-connector-certificate.pem"
-storepass "libertyTrustStorePassword"

In response to the prompt, enter yes to trust the certificate.

The example connector implementation requires the certificate that is used to trust Liberty to also be present in the example-connector directory. Copy the C:\i2\i2analyze\i2-liberty-certificate.pem file to the C:\i2\i2analyze\toolkit\examples\connectors\example-connector directory.

The certificates are now in place to enable client authentication SSL between Liberty and the connector.

Configure the example connector to reference the certificates that you created, and the hostname of the gateway. Using a text editor, modify the security-config.json file with the following values.

https

Set to true to use the HTTPS protocol to connect to the connector.

keyFileName

The file name for the private key of the connector in PEM format. For this example, example-connector-key.pem.

keyPassphrase

The password that is required to access the key file specified in keyFileName. For this example, connectorKeyPassword.

certificateFileName

The file name for the certificate of the connector. For this example, example-connector-certificate.pem.

certificateAuthorityFileName

The file name of the certificate that enables trust of the certificate that is received from Liberty. For this example, i2-liberty-certificate.pem.

gatewayCN

The common name of the gateway. This must be the value of the common name in the certificate the connector receives from Liberty. You specified the value of the CN in the certificate in step 1.

Configure Liberty to use the keystore and truststore that you created.

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.
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.truststore.password=libertyTrustStorePassword
ssl.keystore.password=libertyKeyStorePassword
```
In a command prompt, navigate to the toolkit\scripts directory.
Update the i2 Analyze application:
```
setup -t deployLiberty
```
Start the example connector.
1. In a new command prompt, navigate to the toolkit\examples\connectors\example-connector directory.
2. To start the Node.js server, run the following command:
```
npm start
```
  Note: The example connector uses port number 3700. Ensure that no other processes are using this port number before you start the connector.
Start Liberty:
```
setup -t startLiberty
```

What to do next

Use Analyst's Notebook Premium to connect to your deployment. For more information, see Connecting i2 Analyst's Notebook Premium to i2 Analyze.

Now that the example connector is configured for TLS, no warnings are displayed in Analyst's Notebook Premium.