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 i2 provides as an npm package. 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

Use the Java keytool utility to create a keystore for Liberty that contains a signed certificate for authenticating with the connector. (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"</codeblock>
```
Use the Java keytool utility to create a keystore for the connector that contains a signed certificate for authenticating with Liberty.
1. You need a place to store the connector files. Create a configuration directory for the example connector in the toolkit:
```
mkdir "C:\i2\i2analyze\toolkit\configuration\example-connector"
```
2. 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\configuration\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 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/configuration/example-connector/example-connector-keystore.p12
-out C:/i2/i2analyze/toolkit/configuration/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\configuration\example-connector\example-connector-keystore.p12" -file "C:\i2\i2analyze\toolkit\configuration\example-connector\example-connector-certificate.pem" -rfc -storepass "connectorKeyStorePassword"
```
  Note: The example-connector-keystore.p12 file is not used by the connector and can be removed now that you have extracted the key and certificate.

Use the Java keytool utility to create a truststore for Liberty that contains the certificate that is used to trust the connector:

keytool -importcert -alias "exampleconnector"
-keystore "C:\i2\i2analyze\i2-liberty-truststore.jks"
-file "C:\i2\i2analyze\toolkit\configuration\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 be present in the same directory. Copy the C:\i2\i2analyze\i2-liberty-certificate.pem file to the C:\i2\i2analyze\toolkit\configuration\example-connector directory.
The certificates are now in place to enable client-authenticated SSL between Liberty and the connector.
Next, 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 element 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
```
Finally, configure, download, and start the example connector, and then start Liberty.
1. In a new command prompt, navigate to the toolkit\configuration\example-connector directory.
2. Create a file named .env in the toolkit\configuration\example-connector directory, with the following contents:
```
SSL_ENABLED=true
SSL_SERVER_PORT=3700
SSL_PRIVATE_KEY_FILE="example-connector-key.pem"
SSL_PASSPHRASE="connectorKeyPassword"
SSL_CERTIFICATE_FILE="example-connector-certificate.pem"
SSL_CA_CERTIFICATE_FILE="i2-liberty-certificate.pem"
SSL_GATEWAY_CN="<hostname>"
```
  Note: You specified the value of CN in the certificate in Step 1.
3. Install the dependencies and start the server that hosts the example connector.
  Note: The example connector uses port number 3700. Ensure that no other processes are using this port number before you start the connector.
  Execute the following command:
```
npx @i2analyze/example-connector
```
  Note: You must be connected to the internet to download the package.
4. Start Liberty:
```
setup -t startLiberty
```

What to do next

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

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