Amazon Neptune
User Guide (API Version 2017-11-29)

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

This section shows how to connect to Neptune using the Gremlin Console with Signature Version 4 authentication.


There are limits on the number of concurrent WebSocket connections per database instance, and on how long a connection can remains open. For more information, see WebSockets Limits.


  • Java 8 or higher.

  • Apache Maven 3.3 or higher.

    For information about installing these prerequisites on an EC2 instance running Amazon Linux, see Prerequisites on Amazon Linux EC2.

  • IAM credentials to sign the requests. For more information, see Using the Default Credential Provider Chain.


    If you are using temporary credentials, they expire after a specified interval, including the session token.

    You must update your session token when you request new credentials. For more information, see Using Temporary Security Credentials to Request Access to AWS Resources.

  • Set the SERVICE_REGION variable to one of the following, indicating the Region of your Neptune DB instance:

    • us-east-1

    • us-east-2

    • us-west-2

    • eu-west-1

    • eu-west-2

    • eu-central-1

    • ap-southeast-1

    • ap-southeast-2

    • ap-northeast-1

    • ap-south-1

    • ap-northeast-2

To connect to Neptune using the Gremlin Console with Signature Version 4 signing

  1. Download Gremlin Console (version 3.4.1+) from the Apache Tinkerpop3 website to your EC2 instance.

  2. Unzip the Gremlin Console zip file.

  3. Clone the sample repository from GitHub.

    git clone
  4. Change directory into amazon-neptune-gremlin-java-sigv4.

    cd amazon-neptune-gremlin-java-sigv4
  5. Get the latest version of the project by checking out the branch with the latest tag.

    git checkout $(git describe --tags `git rev-list --tags --max-count=1`)
  6. Build, package, and get the dependencies of the project.

    mvn package dependency:copy-dependencies
  7. Copy the package jar and all dependency jars to the Gremlin Console library directory.

    cp target/{*.jar,dependency/*.jar} ../apache-tinkerpop-gremlin-console-3.4.1/lib
  8. Remove conflicting dependency jars in the Gremlin Console library directory.

    rm ../apache-tinkerpop-gremlin-console-3.4.1/lib/netty-all-4.0.56.Final.jar
  9. Change directories into the unzipped Gremlin Console directory.

    cd ../apache-tinkerpop-gremlin-console-3.4.1
  10. In the conf subdirectory of the extracted directory, create a file named neptune-remote.yaml with the following text. Replace your-neptune-endpoint with the hostname or IP address of your Neptune DB instance. The square brackets ([ ]) are required.


    For information about finding the hostname of your Neptune DB instance, see the Connecting to Amazon Neptune Endpoints section.

    hosts: [your-neptune-endpoint] port: 8182 connectionPool: { channelizer: org.apache.tinkerpop.gremlin.driver.SigV4WebSocketChannelizer} serializer: { className: org.apache.tinkerpop.gremlin.driver.ser.GryoMessageSerializerV3d0, config: { serializeResultToString: true }}
  11. 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|us-east-2|us-west-2|eu-west-1|eu-west-2|eu-central-1|ap-southeast-1|ap-southeast-2|ap-northeast-1|ap-south-1|ap-northeast-2

    The Neptune Version 4 Signer uses the default credential provider chain. For additional methods of providing credentials, see Using the Default Credential Provider Chain.

    The SERVICE_REGION variable is required, even when using a credentials file.

  12. In a terminal, navigate to the Gremlin Console directory (apache-tinkerpop-gremlin-console-3.4.1). Then enter the following command to run the Gremlin Console.


    You should see the following output:

    \,,,/ (o o) -----oOOo-(3)-oOOo----- plugin activated: tinkerpop.server plugin activated: tinkerpop.utilities plugin activated: tinkerpop.tinkergraph gremlin>

    You are now at the gremlin> prompt. You enter the remaining steps at this prompt.

  13. At the gremlin> prompt, enter the following to connect to the Neptune DB instance.

    :remote connect tinkerpop.server conf/neptune-remote.yaml
  14. At the gremlin> prompt, enter the following to switch to remote mode. This sends all Gremlin queries to the remote connection.

    :remote console