Setting Up Secure Connections
Configure the connector to encrypt data in transit.
By default, the connector talks to Couchbase and Elasticsearch over unencrypted socket connections. If encryption is required, you can configure the connector to use TLS/SSL.
Couchbase Server and Elasticsearch both use a root certificate to generate a certificate for each node in the respective cluster.
This guide shows how to obtain the root certificates, and how to tell the connector it should trust these certificates when establishing secure connections.
During the setup process you’ll need access to the Java
This command is included in standard Java distributions under
Couchbase Server Enterprise Edition is required in order to connect to Couchbase over an encrypted connection. Enterprise Edition may be downloaded and evaluated for free. During the download process, see the license agreement for details about commercial use.
Similarly, versions of Elasticsearch prior to 6.8 and 7.1 require an additional license in order to support secure connections. A trial license can be activated by modifying a configuration setting, as explained in the Elasticsearch documentation linked below.
The steps for getting the Couchbase certificate are different depending on whether you are hosting your own Couchbase Server cluster or using Couchbase Cloud.
How to get the certificate for a Couchbase Server cluster you have deployed yourself.
Open the Couchbase Admin Console web UI and click on Security in the navigation sidebar. Then click Root Certificate in the sub-section navigation bar along the top of the page.
|You might see a warning that Couchbase is using a self-signed certificate. That’s fine. This certificate will be added to the connector’s trust store, so it will be trusted regardless of who signed it.|
Copy the certificate into a plain text file.
The filename does not matter, but let’s call it
To use a different root certificate, you can follow instructions on the Configure Server Certificates page.
How to get the certificate for a Couchbase Cloud cluster.
Once you have created a Cluster in Couchbase Cloud, navigate to the
Connect tab and download the security certificate.
Rename the downloaded file to
couchbase.pem. (The name doesn’t really matter, but the rest of this guide refers to the Couchbase certificate file by that name.)
Elasticsearch must first be configured to require TLS/SSL. Please refer to the Elasticsearch documentation, specifically Encrypting communications in Elasticsearch. Make sure you also follow the steps for Encrypting HTTP Client Communications.
|Enabling X-Pack on versions of Elasticsearch prior to 6.8 and 7.1 starts a trial period. When the trial period expires, functionality is degraded unless a license is purchased from Elastic. See Configuring security in Elasticsearch for details.|
As you follow the instructions in the Elasticsearch documentation, you’ll generate a CA certificate for your Elasticsearch cluster (or you might decide to use a well-known public CA, or an internal CA managed by your organization). This CA certificate is the one you’ll add to the connector’s trust store in the next step.
Verify Elasticsearch requires secure connections by opening
https://localhost:9200 in your web browser.
(You might get a warning about an untrusted or self-signed certificate).
You should be prompted for your Elasticsearch credentials, which default to username
elastic with password
The certificates generated by the Amazon Elasticsearch Service are signed by a well-known certificate authority.
When connecting to an instance of the Amazon Elasticsearch Service, you may use the default trust store included with the Java runtime (assuming your Java installation is up-to-date).
This trust store file is usually named
cacerts and lives somewhere under
Alternatively, the Amazon CA certificate may be downloaded from Amazon Trust Services.
The connector’s trust store is a Java keystore file or PKCS12 bundle containing the certificates the connector should trust.
We’ll use the Java
keytool command to create a keystore and populate it with the root certificates for Couchbase and/or Elasticsearch.
To add the Couchbase root certificate:
keytool -importcert -keystore truststore.jks -file couchbase.pem
If the keystore file
truststore.jks does not yet exist, you will be prompted to choose a password for the new keystore.
Otherwise, you will be prompted for the password of the existing keystore.
You will then be presented with a summary of the information in the certificate, and asked if you want to trust the certificate.
If the information is correct, enter
y to confirm.
keytool command again, replacing
couchbase.pem with the path to the Elasticsearch root certificate.
You’re almost done. Now that you have a keystore file containing the CA certificates used by Couchbase and Elasticsearch, you need to tell the connector where to find it.
Edit your connector configuration file and search for the
[truststore] section. Change the associated
path property to match the path to the keystore file.
A relative path will be resolved using the connector installation directory as the base.
This means you can put the
Next, search for the
[couchbase] section and set the
secureConnection property to
Do the same thing in the
Finally, in your connector installation directory, edit the file
secrets/truststore-password.toml and update it with the password you chose.