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

Connecting to Neptune Using Java and Gremlin with Signature Version 4 Signing

This section shows how to connect to Amazon Neptune using the Gremlin Java API 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. See WebSockets Limits for details.


  • Java 8 or higher.

  • Apache Maven 3.3 or higher.

    For information about installing these prerequisites on an Amazon 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 in the AWS SDK for Java Developer Guide.


    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 in the IAM User Guide.

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

    • US East (N. Virginia):   us-east-1

    • US East (Ohio):   us-east-2

    • US West (Oregon):   us-west-2

    • EU (Ireland):   eu-west-1

    • EU (London):   eu-west-2

    • EU (Frankfurt):   eu-central-1

    • Asia Pacific (Singapore):   ap-southeast-1

    • Asia Pacific (Sydney):   ap-southeast-2

    • Asia Pacific (Tokyo):   ap-northeast-1

    • Asia Pacific (Mumbai):   ap-south-1

    • Asia Pacific (Seoul):   ap-northeast-2

    • EU (Stockholm):   eu-north-1

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

  1. Clone the sample repository from GitHub.

    git clone
  2. Change into the cloned directory.

    cd amazon-neptune-gremlin-java-sigv4
  3. 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`)
  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-2 or eu-west-1 or eu-west-2 or eu-central-1 or ap-southeast-1 or ap-southeast-2 or ap-northeast-1 or ap-south-1 or ap-northeast-2 or eu-north-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 AWS SDK for Java Developer Guide.

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

  5. Enter the following command to compile and run the example code.

    Replace your-neptune-endpoint with the hostname or IP address of your Neptune DB instance. The default port is 8182.


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

    mvn compile exec:java \ -Dexec.mainClass="" \ -Dexec.args="-e your-neptune-endpoint -p 8182"
  6. To view the source code for the example, see the file in the src/main/java/com/amazon/neptune/gremlin/driver/example directory.

To use the SigV4 signing driver in your own Java application, add the following to the <dependencies> section of your pom.xml.

<dependency> <groupId>org.apache.tinkerpop</groupId> <artifactId>gremlin-driver</artifactId> <version>3.3.2</version> </dependency> <dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-java-sdk-core</artifactId> <version>1.11.307</version> </dependency> <dependency> <groupId>com.amazonaws</groupId> <artifactId>amazon-neptune-sigv4-signer</artifactId> <version>1.0</version> </dependency> <dependency> <groupId>com.amazonaws</groupId> <artifactId>amazon-neptune-gremlin-java-sigv4</artifactId> <version>1.0</version> </dependency>