Generate Service-Specific Credentials Use the Authentication Plugin

Creating Credentials to Access Amazon Keyspaces (for Apache Cassandra) Programmatically

To provide users and applications with credentials for programmatic access to Amazon Keyspaces resources, you can do either of the following:

Create service-specific credentials that are associated with a specific AWS Identity and Access Management (IAM) user.
Use an authentication plugin for the open-source DataStax Java Driver for Apache Cassandra.

This plugin enables IAM users, roles, and federated identities to add authentication information to Amazon Keyspaces (for Apache Cassandra) API requests using the AWS Signature Version 4 Process (SigV4).

Topics

Generate Service-Specific Credentials
Use the Authentication Plugin

Generate Service-Specific Credentials

Service-specific credentials enable IAM users to access a specific AWS service. The credentials cannot be used to access other AWS services. They are associated with a specific IAM user and cannot be used by other IAM users.

Important

Service-specific credentials can only be used by IAM users. To give IAM roles or federated identities permissions to access your resources, you should use the authentication plugin for the open-source DataStax Java Driver for Apache Cassandra.

Use one of the following procedures to generate a service-specific credential.

To generate service-specific credentials using the console

Sign in to the AWS Management Console and open the Amazon Keyspaces console at https://console.aws.amazon.com/iam/home.
In the navigation pane, choose Users, and then choose the user that you created earlier that has Amazon Keyspaces permissions (policy attached).
Choose Security Credentials. Under Credentials for Amazon Keyspaces, choose Generate credentials to generate the service-specific credentials.

Your service-specific credentials are now available. This is the only time you can download or view the password. You cannot recover it later. However, you can reset your password at any time. Save the user and password in a secure location, because you'll need them later.

To generate service-specific credentials using the AWS CLI

Before generating service-specific credentials, you need to download, install, and configure the AWS Command Line Interface (AWS CLI):

Download the AWS CLI at http://aws.amazon.com/cli.

Note

The AWS CLI runs on Windows, macOS, or Linux.
Follow the instructions for Installing the AWS CLI and Configuring the AWS CLI in the AWS Command Line Interface User Guide.
Using the AWS CLI, run the following command to generate service-specific credentials for the user alice, so that she can access Amazon Keyspaces.
```
aws iam create-service-specific-credential \
    --user-name alice \
    --service-name cassandra.amazonaws.com
```

The output looks like the following.


{
    "ServiceSpecificCredential": {
        "CreateDate": "2019-10-09T16:12:04Z",
        "ServiceName": "cassandra.amazonaws.com",
        "ServiceUserName": "alice-at-111122223333",
        "ServicePassword": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
        "ServiceSpecificCredentialId": "ACCAYFI33SINPGJEBYESF",
        "UserName": "alice",
        "Status": "Active"
    }
}

In the output, note the values for ServiceUserName and ServicePassword. Save these values in a secure location, because you'll need them later.

Important

This is the only time that the ServicePassword will be available to you.

Use the Authentication Plugin for the DataStax Java Driver for Apache Cassandra

The following sections describe how to use the 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.

Authentication Plugin for Amazon Keyspaces

You can use the authentication plugin to add authentication information to your Amazon Keyspaces API requests by using the Signature Version 4 (SigV4) Signing Process.

Topics

SSL Configuration
Region Configuration
Add the Authentication Plugin to the Application
How to use the Authentication Plugin

SSL Configuration

The first step is to get an Amazon digital certificate to encrypt your connections using Transport Layer Security (TLS). The DataStax Java driver must use an SSL trust store so that the client SSL engine can validate the Amazon Keyspaces certificate on connection. To use the trust store and create a certificate, see Using a Cassandra Java Client Driver to Access Amazon Keyspaces Programmatically.

Region Configuration

Before you can start using the plugin, you must configure the AWS Region that the plugin will use when authenticating. This is required because SigV4 signatures are Region-specific. For example, if you are connecting to the cassandra.us-east-2.amazonaws.com endpoint, the Region must be us-east-2. For a list of available AWS Regions and endpoints, see Service Endpoints for Amazon Keyspaces.

You can specify the Region using one of the following four methods:

Environment Variable
System Property
Constructor
Configuration

Environment Variable

You can use the AWS_REGION environment variable to match the endpoint that you are communicating with by setting it as part of your application start-up, as follows.


$ export AWS_Region=us-east-1

System Property

You can use the aws.region Java system property by specifying it on the command line, as follows.


$ java -Daws.region=us=east-1 ...

Constructor

One of the constructors for software.aws.mcs.auth.SigV4AuthProvider takes a String representing the Region that will be used for that instance.

Configuration

Set the Region explicitly in your advanced.auth-provider.class configuration (see example below), by specifying the advanced.auth-provider.aws-region property.

Add the Authentication Plugin to the 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>

How to use the Authentication Plugin

When using the open-source DataStax Java driver, the connection to Amazon Keyspaces is represented by the CqlSession class. To create the CqlSession, you can either configure it programmatically or with the configuration file.

Programmatically Configure the Driver

You can create an instance of CqlSession using the CqlSession.builder() function. CqlSession.builder() enables you to specify another authentication provider for the session by using the with withAuthProvider function.

To use the authentication plugin, you set a Region-specific instance of SigV4AuthProvider as the authentication provider, as in the following example.

Call addContactPoints on the builder with a collection of java.net.InetSocketAddress instances corresponding to the endpoints for your Region.

Contact points are the endpoints that the driver will connect to. For a full list of endpoints and Regions in the documentation, see Service Endpoints for Amazon Keyspaces.
Add an SSL context by calling withSslContext on the builder.

This uses the trust store defined previously to negotiate SSL on the connection to the endpoints. SSL is required for Amazon Keyspaces. Without this setting, connections will time out and fail.
Set the local data center to the region name, in this example it is us-east-2.

The local data center is used by the driver for routing of requests, and it is required when the builder is constructed with addContactPoints.
Set the authentication provider to a new instance of software.aws.mcs.auth.SigV4AuthProvider.

The SigV4AuthProvider is the authentication handler provided by the plugin for performing SigV4 authentication. You can specify the Region for the endpoints that you’re using in the constructor for SigV4AuthProvider, as in the following example. Or, you can set the environment variable or system property as shown previously.

The following code example demonstrates the previous steps.


List<InetSocketAddress> contactPoints =
      Collections.singletonList(
       InetSocketAddress.createUnresolved("cassandra.us-east-2.amazonaws.com", 9142));


    try (CqlSession session = CqlSession.builder()
      .addContactPoints(contactPoints)
      .withSslContext(SSLContext.getDefault())
      .withLocalDatacenter("us-east-2")
      .withAuthProvider(new SigV4AuthProvider("us-east-2"))
      .build()) {
      // App code here...
    }

Use a Configuration File

To use the configuration file, set the advanced.auth-provider.class to software.aws.mcs.auth.SigV4AuthProvider. You can also set the local data center and enable SSL in the configuration.

Set the advanced.auth-provider.class to software.aws.mcs.auth.SigV4AuthProvider.
Set local-datacenter to us-east-2.

The following is an example of this.


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
            }
        }
    }

Warning Javascript is disabled or is unavailable in your browser.

To use the AWS Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Connecting Programmatically

Service Endpoints