Skip to content

Commit 20e8e2a

Browse files
dchenbecdchenbec
authored
Update README
Add in updated instructions for usage
1 parent efc0f18 commit 20e8e2a

File tree

1 file changed

+114
-1
lines changed

1 file changed

+114
-1
lines changed

‎README.md‎

Lines changed: 114 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,120 @@ constructor programmatically, via the `AWS_REGION` environment variable, or via
77
match the endpoint you're communicating with.
88

99
The full documentation for the plugin can be found at
10-
https://docs.aws.amazon.com/mcs/latest/devguide/programmatic.credentials.html#programmatic.credentials.SigV4_MCS.
10+
https://docs.aws.amazon.com/mcs/latest/devguide/programmatic.credentials.html#programmatic.credentials.SigV4_MCS
11+
12+
# Using the Plugin
13+
14+
The following sections describe how to use the authentication plugin for the open-source DataStax Java Driver for Cassandra to access Amazon Managed Apache Cassandra Service.
15+
16+
## SSL Configuration
17+
18+
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 Managed Cassandra Service certificate on connection. To use the trust store and create a certificate, see [Using a Cassandra Java Client Driver to Access Amazon Managed Cassandra Service Programmatically](https://docs.aws.amazon.com/mcs/latest/devguide/programmatic.drivers.html#using_java_driver).
19+
20+
## Region Configuration
21+
22+
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 Managed Cassandra Service](https://docs.aws.amazon.com/mcs/latest/devguide/programmatic.endpoints.html).
23+
24+
You can specify the Region using one of the following four methods:
25+
26+
* Environment Variable
27+
* System Property
28+
* Constructor
29+
* Configuration
30+
31+
## Environment Variable
32+
33+
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.
34+
35+
``` shell
36+
$ export AWS_Region=us-east-1
37+
```
38+
## System Property
39+
40+
You can use the `aws.region` Java system property by specifying it on the command line, as follows.
41+
42+
``` shell
43+
$ java -Daws.region=us=east-1 ...
44+
```
45+
46+
## Constructor
47+
48+
One of the constructors for `software.aws.mcs.auth.SigV4AuthProvider` takes a `String` representing the Region that will be used for that instance.
49+
50+
## Configuration
51+
52+
Set the Region explicitly in your `advanced.auth-provider.class` configuration (see example below), by specifying the `advanced.auth-provider.aws-region` property.
53+
54+
## Add the Authentication Plugin to the Application
55+
56+
The authentication plugin supports version 4.x of the DataStax Java Driver for 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.
57+
58+
``` xml
59+
<dependency>
60+
<groupId>software.aws.mcs</groupId>
61+
<artifactId>aws-sigv4-auth-cassandra-java-driver-plugin</artifactId>
62+
<version>4.0.0</version>
63+
</dependency>
64+
```
65+
66+
## How to use the Authentication Plugin
67+
68+
When using the open-source DataStax Java driver, the connection to your Amazon Managed Cassandra Service cluster is represented by the `CqlSession` class. To create the `CqlSession`, you can either configure it programmatically using the `CqlSessionBuilder` class (accessed via `CqlSession.builder()`) or with the configuration file.
69+
70+
### Programmatically Configure the Driver
71+
72+
When using the DataStax Java driver, you interact with Amazon Managed Cassandra Service primarily through the `CQLSession` class. 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.
73+
74+
To use the authentication plugin, you set a Region-specific instance of SigV4AuthProvider as the authentication provider, as in the following example.
75+
76+
1. 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 Managed Cassandra Service](https://docs.aws.amazon.com/mcs/latest/devguide/programmatic.endpoints.html).
77+
1. 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 Managed Cassandra Service. Without this setting, connections will time out and fail.
78+
1. 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`.
79+
1. 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.
80+
81+
The following code example demonstrates the previous steps.
82+
83+
``` java
84+
List<InetSocketAddress> contactPoints =
85+
Collections.singletonList(
86+
InetSocketAddress.createUnresolved("cassandra.us-east-2.amazonaws.com", 9142));
87+
88+
try (CqlSession session = CqlSession.builder()
89+
.addContactPoints(contactPoints)
90+
.withSslContext(SSLContext.getDefault())
91+
.withLocalDatacenter("us-east-2")
92+
.withAuthProvider(new SigV4AuthProvider("us-east-2"))
93+
.build()) {
94+
// App code here...
95+
}
96+
```
97+
98+
### Use a Configuration File
99+
100+
To use the configuration file, set the `advanced.auth-provider.class` to `software.aws.mcs.auth.SigV4AuthProvider`. You can also set the region, local data center and enable SSL in the configuration.
101+
102+
1. Set the `advanced.auth-provider.class` to `software.aws.mcs.auth.SigV4AuthProvider`.
103+
1. Set `basic.load-balancing-policy.local-datacenter` to the region name. In this case, use `us-east-2`.
104+
105+
The following is an example of this.
106+
107+
``` text
108+
datastax-java-driver {
109+
basic.load-balancing-policy {
110+
class = DefaultLoadBalancingPolicy
111+
local-datacenter = us-east-2
112+
}
113+
advanced {
114+
auth-provider = {
115+
class = software.aws.mcs.auth.SigV4AuthProvider
116+
aws-region = us-east-2
117+
}
118+
ssl-engine-factory {
119+
class = DefaultSslEngineFactory
120+
}
121+
}
122+
}
123+
```
11124

12125
# Example Usage
13126

0 commit comments

Comments
 (0)