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

IAM Authentication using Temporary Credentials

Amazon Neptune supports IAM authentication using temporary credentials.

You can use an assumed role to authenticate using an IAM authentication policy, like one of the example policies in the previous sections.

If you are using temporary credentials, you must specify AWS_SESSION_TOKEN in addition to AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and SERVICE_REGION.

Note

The temporary credentials expire after a specified interval, including the session token.

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

The following sections describe how to allow access and retrieve temporary credentials.

To Authenticate using Temporary Credentials

  1. Create an IAM role with permission to access a Neptune cluster. For information on creating this role, see Creating and Using an IAM Policy for IAM Database Access.

  2. Add a trust relationship to the role that allows access to the credentials.

    Retrieve the temporary credentials, including the AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN.

  3. Connect to the Neptune cluster and sign the requests using the temporary credentials. For more information on connecting and signing requests, see Connecting and Signing with AWS Signature Version 4.

There are various methods for retrieving temporary credentials depending on the environment.

Get Credentials with the AWS CLI

To get credentials using the AWS CLI, first you need to add a trust relationship that grants permission to assume the role to the AWS user that will run the CLI command.

Add the following trust relationship to the Neptune IAM authentication role. If you don't have a Neptune IAM authentication role, see Creating and Using an IAM Policy for IAM Database Access.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::123456789012:user/test" }, "Action": "sts:AssumeRole" } ] }

For information on adding the trust relationship to the role, see Editing the Trust Relationship for an Existing Role.

If the Neptune policy is not yet attached to a role, create a new role, attach the Neptune IAM authentication policy, and then add the trust policy. For information on creating a new role, see see Create Role.

Note

The following sections assume you have the AWS CLI installed.

Run the CLI Manually

  1. Type the following command to request the credentials using the CLI. Replace th role ARN, session name, and profile with your own values.

    aws sts assume-role --role-arn arn:aws:iam::123456789012:role/NeptuneIAMAuthRole --role-session-name test --profile testprofile
  2. The following is example output from the command. The Credentials section contains the values you need.

    Note

    Record the Expiration value as you will need to get new credentials after this time.

    { "AssumedRoleUser": { "AssumedRoleId": "AROA3XFRBF535PLBIFPI4:s3-access-example", "Arn": "arn:aws:sts::123456789012:assumed-role/xaccounts3access/s3-access-example" }, "Credentials": { "SecretAccessKey": "9drTJvcXLB89EXAMPLELB8923FB892xMFI", "SessionToken": "AQoXdzELDDY//////////wEaoAK1wvxJY12r2IrDFT2IvAzTCn3zHoZ7YNtpiQLF0MqZye/qwjzP2iEXAMPLEbw/m3hsj8VBTkPORGvr9jM5sgP+w9IZWZnU+LWhmg+a5fDi2oTGUYcdg9uexQ4mtCHIHfi4citgqZTgco40Yqr4lIlo4V2b2Dyauk0eYFNebHtYlFVgAUj+7Indz3LU0aTWk1WKIjHmmMCIoTkyYp/k7kUG7moeEYKSitwQIi6Gjn+nyzM+PtoA3685ixzv0R7i5rjQi0YE0lf1oeie3bDiNHncmzosRM6SFiPzSvp6h/32xQuZsjcypmwsPSDtTPYcs0+YN/8BRi2/IcrxSpnWEXAMPLEXSDFTAQAM6Dl9zR0tXoybnlrZIwMLlMi1Kcgo5OytwU=", "Expiration": "2016-03-15T00:05:07Z", "AccessKeyId": "ASIAJEXAMPLEXEG2JICEA" } }
  3. Set environment variables using the returned credentials.

    export AWS_ACCESS_KEY_ID=ASIAJEXAMPLEXEG2JICEA export AWS_SECRET_ACCESS_KEY=9drTJvcXLB89EXAMPLELB8923FB892xMFI export AWS_SESSION_TOKEN=AQoXdzELDDY//////////wEaoAK1wvxJY12r2IrDFT2IvAzTCn3zHoZ7YNtpiQLF0MqZye/qwjzP2iEXAMPLEbw/m3hsj8VBTkPORGvr9jM5sgP+w9IZWZnU+LWhmg+a5fDi2oTGUYcdg9uexQ4mtCHIHfi4citgqZTgco40Yqr4lIlo4V2b2Dyauk0eYFNebHtYlFVgAUj+7Indz3LU0aTWk1WKIjHmmMCIoTkyYp/k7kUG7moeEYKSitwQIi6Gjn+nyzM+PtoA3685ixzv0R7i5rjQi0YE0lf1oeie3bDiNHncmzosRM6SFiPzSvp6h/32xQuZsjcypmwsPSDtTPYcs0+YN/8BRi2/IcrxSpnWEXAMPLEXSDFTAQAM6Dl9zR0tXoybnlrZIwMLlMi1Kcgo5OytwU= export SERVICE_REGION=us-east-1|us-east-2|us-west-2|eu-west-1|eu-west-2|eu-central-1
  4. Connect using one of the following methods.

Use a Script to Get the Credentials

  1. Run the following command to install the jq command. The script uses this command to parse the output of the AWS CLI command.

    sudo yum -y install jq
  2. Create a file named credentials.sh in a text editor and add the following text. Replace the service region, role ARN, session name, and profile with your own values.

    #!/bin/bash creds_json=$(aws sts assume-role --role-arn arn:aws:iam::123456789012:role/NeptuneIAMAuthRole --role-session-name test --profile testprofile) export AWS_ACCESS_KEY_ID=$(echo "$creds_json" | jq .Credentials.AccessKeyId |tr -d '"') export AWS_SECRET_ACCESS_KEY=$(echo "$creds_json" | jq .Credentials.SecretAccessKey| tr -d '"') export AWS_SESSION_TOKEN=$(echo "$creds_json" | jq .Credentials.SessionToken|tr -d '"') export SERVICE_REGION=us-east-1|us-east-2|us-west-2|eu-west-1|eu-west-2|eu-central-1
  3. Connect using one of the following methods.

Setup AWS Lambda for Neptune IAM Authentication

AWS Lambda will include credentials automatically each time the Lambda function is ran.

First you need to add a trust relationship that grants permission to assume the role to the AWS Lambda service.

Add the following trust relationship to the Neptune IAM authentication role. If you don't have a Neptune IAM authentication role, see Creating and Using an IAM Policy for IAM Database Access.

{ "Version": "2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "lambda.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }

For information on adding the trust relationship to the role, see Editing the Trust Relationship for an Existing Role.

If the Neptune policy is not yet attached to a role, create a new role, attach the Neptune IAM authentication policy, and then add the trust policy. For information on creating a new role, see see Create Role.

To Access Neptune from Lambda

  1. Sign in to the AWS Management Console and open the AWS Lambda console at https://console.aws.amazon.com/lambda/.

  2. Create a new Lambda function for Python version 3.6.

  3. Assign the AWSLambdaVPCAccessExecutionRole role to the Lambda function. This is required to access Neptune resources, which are VPC only.

  4. Assign the Neptune authentication IAM role to the Lambda function.

    For more information, see AWS Lambda Permissions Model.

  5. Copy the IAM authentication Python sample into the Lambda funciton code. For more information on the sample and the sample code, see Connect to Neptune Using Python with Version 4 Signing (Example).

Setup Amazon EC2 for Neptune IAM Authentication

Amazon EC2 allows you to use instance profiles to automatically provide credentials. For more information, see Using Instance Profiles.

First you need to add a trust relationship that grants permission to assume the role to the Amazon EC2 service.

Add the following trust relationship to the Neptune IAM authentication role. If you don't have a Neptune IAM authentication role, see Creating and Using an IAM Policy for IAM Database Access.

{ "Version": "2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "ec2.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }

For information on adding the trust relationship to the role, see Editing the Trust Relationship for an Existing Role.

If the Neptune policy is not yet attached to a role, create a new role, attach the Neptune IAM authentication policy, and then add the trust policy. For information on creating a new role, see see Create Role.

Use a Script to Get the Credentials

  1. Run the following command to install the jq command. The script uses this command to parse the output of the curl command.

    sudo yum -y install jq
  2. Create a file named credentials.sh in a text editor and add the following text. Replace the service region with your own value.

    #!/bin/bash role_name=$( curl -s http://169.254.169.254/latest/meta-data/iam/security-credentials/ ) creds_json=$(curl -s http://169.254.169.254/latest/meta-data/iam/security-credentials/${role_name}) export AWS_ACCESS_KEY_ID=$(echo "$creds_json" | jq .AccessKeyId |tr -d '"') export AWS_SECRET_ACCESS_KEY=$(echo "$creds_json" | jq .SecretAccessKey| tr -d '"') export AWS_SESSION_TOKEN=$(echo "$creds_json" | jq .Token|tr -d '"') export SERVICE_REGION=us-east-1|us-east-2|us-west-2|eu-west-1|eu-west-2|eu-central-1
  3. Connect using one of the following methods.