Using a Cassandra Java Client Driver to Access Amazon Keyspaces Programmatically - Amazon Keyspaces (for Apache Cassandra)

Using a Cassandra Java Client Driver to Access Amazon Keyspaces Programmatically

This section shows you how to connect to Amazon Keyspaces by using a Java client driver. To provide users and applications with credentials for programmatic access to Amazon Keyspaces resources, you can do either of the following:

Before You Begin

Amazon Keyspaces requires the use of Transport Layer Security (TLS) to help secure connections with clients. To connect to Amazon Keyspaces using TLS, you need to complete the following tasks before you can start.

  1. Download the Amazon digital certificate using the following command and save it to the path_to_file/.cassandra directory.

    curl https://www.amazontrust.com/repository/AmazonRootCA1.pem -O
  2. Convert the Amazon digital certificate to a trustStore file:

    openssl x509 -outform der -in AmazonRootCA1.pem -out temp_file.der keytool -import -alias cassandra -keystore cassandra_truststore.jks -file temp_file.der
  3. Attach the trustStore file in the JVM arguments:

    -Djavax.net.ssl.trustStore=path_to_file/cassandra_truststore.jks -Djavax.net.ssl.trustStorePassword=my_password

Step-by-Step Tutorial to Connect to Amazon Keyspaces Using the DataStax Java Driver for Apache Cassandra using Service-Specific Credentials

The following step-by-step tutorial walks you through connecting to Amazon Keyspaces using a Java driver for Cassandra using service-specific credentials. Specifically, you'll use the 4.0 version of the DataStax Java Driver for Apache Cassandra.

Step 1: Pre-Requisites

To follow this tutorial, you need to generate service-specific credentials and add the DataStax Java Driver for Apache Cassandra to your Java project.

Step 2: Configure the Driver

You can specify settings for the DataStax Java Cassandra driver by creating a configuration file for your application. This configuration file overrides the default settings and tells the driver to connect to the Amazon Keyspaces service endpoint using port 9142. For a list of available service endpoints, see Service Endpoints for Amazon Keyspaces.

Create a configuration file and save the file in the application's resources folder—for example, src/main/resources/application.conf. Open application.conf and add the following configuration settings.

  1. Authentication provider – Create the authentication provider with the PlainTextAuthProvider class. ServiceUserName and ServicePassword should match the user name and password you obtained when you generated the service-specific credentials by following the steps in Generate Service-Specific Credentials.

    Note

    You can use short-term credentials by using the authentication plugin for the DataStax Java Driver for Apache Cassandra instead of hardcoding credentials in your driver configuration file. To learn more, follow the instructions for the Step-by-Step Tutorial to Connect to Amazon Keyspaces Using the DataStax Java Driver for Apache Cassandra and the SigV4 Authentication Plugin.

  2. Local data center – Set the value for local-datacenter to the Region you're connecting to. For example, if the application is connecting to cassandra.us-east-2.amazonaws.com, then set the local data center to us-east-2. For all available AWS Regions, see Service Endpoints for Amazon Keyspaces.

  3. SSL/TLS – Initialize the SSLEngineFactory by adding a section in the configuration file with a single line that specifies the class with class = DefaultSslEngineFactory. Provide the path to the trustStore file and the password that you created previously.

datastax-java-driver { basic.contact-points = [ "cassandra.us-east-2.amazonaws.com:9142"] advanced.auth-provider{ class = PlainTextAuthProvider username = "ServiceUserName" password = "ServicePassword" } basic.load-balancing-policy { local-datacenter = "us-east-2" } advanced.ssl-engine-factory { class = DefaultSslEngineFactory truststore-path = "./src/main/resources/cassandra_truststore.jks" truststore-password = "my_password" } }
Note

Instead of adding the path to the trustStore in the configuration file, you can also add the trustStore path directly in the application code or you can add the path to the trustStore to your JVM arguments.

Step 3: Run the Sample Application

This code example shows a simple command line application that creates a connection pool to Amazon Keyspaces by using the configuration file we created earlier. It confirms that the connection is established by running a simple query.

package <your package>; // add the following imports to your project import com.datastax.oss.driver.api.core.CqlSession; import com.datastax.oss.driver.api.core.config.DriverConfigLoader; import com.datastax.oss.driver.api.core.cql.ResultSet; import com.datastax.oss.driver.api.core.cql.Row; public class App { public static void main( String[] args ) { //Use DriverConfigLoader to load your configuration file DriverConfigLoader loader = DriverConfigLoader.fromClasspath("application.conf"); try (CqlSession session = CqlSession.builder() .withConfigLoader(loader) .build()) { ResultSet rs = session.execute("select * from system_schema.keyspaces"); Row row = rs.one(); System.out.println(row.getString("keyspace_name")); } } }
Note

Use a try block to establish the connection to ensure that it's always closed. If you don't use a try block, remember to close your connection to avoid leaking resources.

Step-by-Step Tutorial to Connect to Amazon Keyspaces Using the DataStax Java Driver for Apache Cassandra and the SigV4 Authentication Plugin

The following sections describe how to use the SigV4 authentication plugin for the open-source DataStax Java Driver for Apache Cassandra to access Amazon Keyspaces (for Apache Cassandra). The plugin is available from the GitHub repository.

Step 1: Pre-Requisites

To follow this tutorial, you need to complete the following tasks.

  • Add the DataStax Java Driver for Apache Cassandra to your Java project. Ensure that you're using a version of the driver that supports Apache Cassandra 3.11.2. For more information, see the DataStax Java Driver for Apache Cassandra documentation.

  • Add the authentication plugin to your application. The authentication plugin supports version 4.x of the DataStax Java Driver for Apache Cassandra. If you’re using Apache Maven, or a build system that can use Maven dependencies, add the following dependencies to your pom.xml file. Replace the version of the plugin with the latest version as shown at GitHub repository.

    <dependency> <groupId>software.aws.mcs</groupId> <artifactId>aws-sigv4-auth-cassandra-java-driver-plugin</artifactId> <version>4.0.2</version> </dependency>

Step 2: Configure the Driver

You can specify settings for the DataStax Java Cassandra driver by creating a configuration file for your application. This configuration file overrides the default settings and tells the driver to connect to the Amazon Keyspaces service endpoint using port 9142. For a list of available service endpoints, see Service Endpoints for Amazon Keyspaces.

Create a configuration file and save the file in the application's resources folder—for example, src/main/resources/application.conf. Open application.conf and add the following configuration settings.

  1. Authentication provider – Set the advanced.auth-provider.class to a new instance of software.aws.mcs.auth.SigV4AuthProvider. The SigV4AuthProvider is the authentication handler provided by the plugin for performing SigV4 authentication.

  2. Local data center – Set the value for local-datacenter to the Region you're connecting to. For example, if the application is connecting to cassandra.us-east-2.amazonaws.com, then set the local data center to us-east-2. For all available AWS Regions, see Service Endpoints for Amazon Keyspaces.

  3. SSL/TLS – Initialize the SSLEngineFactory by adding a section in the configuration file with a single line that specifies the class with class = DefaultSslEngineFactory. Provide the path to the trustStore file and the password that you created previously.

datastax-java-driver { basic.load-balancing-policy { class = DefaultLoadBalancingPolicy local-datacenter = us-east-2 } advanced { auth-provider = { class = software.aws.mcs.auth.SigV4AuthProvider aws-region = us-east-2 } ssl-engine-factory { class = DefaultSslEngineFactory } } }
Note

Instead of adding the path to the trustStore in the configuration file, you can also add the trustStore path directly in the application code or you can add the path to the trustStore to your JVM arguments.

Step 3: Run the application

This code example shows a simple command line application that creates a connection pool to Amazon Keyspaces by using the configuration file we created earlier. It confirms that the connection is established by running a simple query.

package <your package>; // add the following imports to your project import com.datastax.oss.driver.api.core.CqlSession; import com.datastax.oss.driver.api.core.config.DriverConfigLoader; import com.datastax.oss.driver.api.core.cql.ResultSet; import com.datastax.oss.driver.api.core.cql.Row; public class App { public static void main( String[] args ) { //Use DriverConfigLoader to load your configuration file DriverConfigLoader loader = DriverConfigLoader.fromClasspath("application.conf"); try (CqlSession session = CqlSession.builder() .withConfigLoader(loader) .build()) { ResultSet rs = session.execute("select * from system_schema.keyspaces"); Row row = rs.one(); System.out.println(row.getString("keyspace_name")); } } }
Note

Use a try block to establish the connection to ensure that it's always closed. If you don't use a try block, remember to close your connection to avoid leaking resources.