AWS neptune documentation change
Summary
Added version-specific instructions for connecting to Neptune with Sigv4 authentication, splitting documentation into TinkerPop 3.4.11+ and older versions. Added detailed steps for credential configuration and proxy handling.
Security assessment
The changes enhance documentation about implementing Sigv4 authentication (AWS signature version 4), which is a security feature for API request signing. However, there is no evidence of addressing a specific vulnerability - rather improving existing security documentation. The additions about credential environment variables and service region requirements reinforce security best practices.
Diff
diff --git a/neptune/latest/userguide/iam-auth-connecting-gremlin-console.md b/neptune/latest/userguide/iam-auth-connecting-gremlin-console.md index ed4c7a4f9..fa52d1cfe 100644 --- a//neptune/latest/userguide/iam-auth-connecting-gremlin-console.md +++ b//neptune/latest/userguide/iam-auth-connecting-gremlin-console.md @@ -4,0 +5,2 @@ +Using TinkerPop 3.4.11 or higherBefore TinkerPop 3.4.11 + @@ -7 +9 @@ -There are two prerequisites to connecting Amazon Neptune using Gremlin Console with Signature Version 4 authentication: +How you connect to Amazon Neptune using the Gremlin console with Signature Version 4 authentication depends on whether you are using TinkerPop version `3.4.11` or higher, or an earlier version. In either case, the following prerequisites are necessary: @@ -20 +22,3 @@ For help connecting using SSL/TLS, see [SSL/TLS configuration](./access-graph-gr -The `:remote` command is used to create a connection from the Gremlin Console to Neptune. You will use the `requestInterceptor()` to plug-in a Sigv4 signer to that connection to authenticate it over IAM. +## Using TinkerPop 3.4.11 or higher to connect to Neptune with Sig4 signing + +With TinkerPop 3.6.6 or higher, you will use `requestInterceptor()`, which provides a way to plug in a Sigv4 signer to the connection established by the `:remote` command. As with the approach used for Java, it requires you to configure the `Cluster` object manually and then pass it to the `:remote` command. @@ -24 +28 @@ Note that this is quite different from the typical situation where the `:remote` -###### Connect the Gremlin console with Sigv4 signing +###### Connect the Gremlin console (TinkerPop 3.4.11 and higher) with Sig4 signing @@ -84,0 +89,65 @@ For help finding the host name of a Neptune DB instance, see [Connecting to Amaz +## Using a version of TinkerPop earlier than 3.4.11 to connect to Neptune with Sig4 signing + +With TinkerPop 3.4.10 or lower, use the `amazon-neptune-gremlin-java-sigv4` library provided by Neptune to connect the console to Neptune with Sigv4 signing, as described below: + +###### Connect the Gremlin console (TinkerPop versions earlier than 3.4.11) with Sig4 signing + + 1. Start the Gremlin console: + + $ bin/gremlin.sh + + 2. At the `gremlin>` prompt, install the `amazon-neptune-sigv4-signer` library (this only needs to be done once for the console): + + :install com.amazonaws amazon-neptune-sigv4-signer 2.4.0 + +###### Note + +If you are using an HTTP proxy, you may encounter errors with this step where the `:install` command does not complete. To solve this problem, run the following commands to tell the console about the proxy: + + System.setProperty("https.proxyHost", "(the proxy IP address)") + System.setProperty("https.proxyPort", "(the proxy port)") + +It may also help to consult the [TinkerPop documentation](https://tinkerpop.apache.org/docs/current/reference/#gremlin-applications) about [Grape](http://docs.groovy-lang.org/latest/html/documentation/grape.html) configuration. + + 3. In the `conf` subdirectory of the extracted directory, create a file named `neptune-remote.yaml`. + +If you used the CloudFormation template to create your Neptune DB cluster, a `neptune-remote.yaml` file will already exist. In that case, all you have to do is edit the existing file to include the channelizer setting shown below. + +Otherwise, copy the following text into the file, replacing `(host name)` with the host name or IP address of your Neptune DB instance. Note that the square brackets ([ ]) enclosing the host name are required. + + hosts: [(host name)] + port: 8182 + connectionPool: { + channelizer: org.apache.tinkerpop.gremlin.driver.SigV4WebSocketChannelizer, + enableSsl: true + } + serializer: { className: org.apache.tinkerpop.gremlin.driver.ser.GraphBinaryMessageSerializerV1, + config: { serializeResultToString: true }} + + 4. ###### Important + +You must provide IAM credentials to sign the requests. Enter the following commands to set your credentials as environment variables, replacing the relevant items with your credentials. + + export AWS_ACCESS_KEY_ID=access_key_id + export AWS_SECRET_ACCESS_KEY=secret_access_key + export SERVICE_REGION=us-east-1 or us-east-2 or us-west-1 or us-west-2 or ca-central-1 or + sa-east-1 or eu-north-1 or eu-west-1 or eu-west-2 or eu-west-3 or eu-central-1 or me-south-1 or + me-central-1 or il-central-1 or af-south-1 or ap-east-1 or ap-northeast-1 or ap-northeast-2 or ap-southeast-1 or ap-southeast-2 or ap-south-1 or + cn-north-1 or cn-northwest-1 or + us-gov-east-1 or us-gov-west-1 + +The Neptune Version 4 Signer uses the default credential provider chain. For additional methods of providing credentials, see [Using the Default Credential Provider Chain](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html#credentials-default) in the _AWS SDK for Java Developer Guide_. + +The `SERVICE_REGION` variable is required, even when using a credentials file. + + 5. Establish the `:remote` connection using the `.yaml` file: + + :remote connect tinkerpop.server conf/neptune-remote.yaml + + 6. Enter the following command to switch to remote mode, which sends all Gremlin queries to the remote connection: + + :remote console + + + +