Connecting to Neptune Using the Gremlin Console with Signature Version 4 Signing - Amazon Neptune
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.

Connecting to Neptune Using the Gremlin Console with Signature Version 4 Signing

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:

  • You must have the IAM credentials needed to sign the requests. See Using the default credential provider chain in the Amazon SDK for Java Developer Guide.

  • You must have installed a Gremlin console version that is compatible with the version of the Neptune engine being used by your DB cluster.

If you are using temporary credentials, they expire after a specified interval, as does the session token, so you must update your session token when you request new credentials. See Using temporary security credentials to request access to Amazon resources in the IAM User Guide.

For help connecting using SSL/TLS, see SSL/TLS configuration.

Using TinkerPop 3.4.11 or higher to connect to Neptune with Sig4 signing

With TinkerPop 3.4.11 or higher, you will use handshakeInterceptor(), 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.

Note that this is quite different from the typical situation where the :remote command takes a configuration file to form the connection. The configuration file approach won't work because handshakeInterceptor() must be set programmatically, and can't load its configuration from a file.

Connect the Gremlin console (TinkerPop 3.4.11 and higher) 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

    If you encounter problems with this step, it may help to consult the TinkerPop documentation about Grape configuration.

  3. Import the class required to handle the signing into handshakeInterceptor():

    :import com.amazonaws.auth.DefaultAWSCredentialsProviderChain :import com.amazonaws.neptune.auth.NeptuneNettyHttpSigV4Signer
  4. If you haven't otherwise established your account credentials, you can assign them as follows:

    System.setProperty("aws.accessKeyId","(your access key)") System.setProperty("aws.secretKey","(your secret key)")
  5. Manually construct the Cluster object to connect to Neptune:

    cluster = Cluster.build("(host name)") .enableSsl(true) .handshakeInterceptor{ r -> def sigV4Signer = new NeptuneNettyHttpSigV4Signer("(Amazon region)", new DefaultAWSCredentialsProviderChain()) sigV4Signer.signRequest(r) return r } .create()

    For help finding the host name of a Neptune DB instance, see Connecting to Amazon Neptune Endpoints.

  6. Establish the :remote connection using the variable name of the Cluster object in the previous step:

    :remote connect tinkerpop.server cluster
  7. Enter the following command to switch to remote mode. This sends all Gremlin queries to the remote connection:

    :remote console

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

    If you encounter problems with this step, it may help to consult the TinkerPop documentation about Grape configuration.

  3. In the conf subdirectory of the extracted directory, create a file named neptune-remote.yaml.

    If you used the Amazon 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 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 in the Amazon 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